Communicating well via written word is a core skill for remote organisations. This guide deals with how to write good evergreen documents and builds on the advice in Lean Documentation.
More on Lean Documentation - The MVD
Core Principles 📜
There are five core principles that apply to writing evergreen documents in any Wiki-type system…
- Make it obvious
- Make it pretty
- Keep it flat
- Have things explain themselves
- Build for the future
1️⃣ Make it obvious
Write in plain english and put yourself in the shoes of the reader. Second-guess the questions in their head. Avoid acronyms. Take some time to explain the why of things as well as the what and the how. Make it obvious how to use your document and who should read it. Use formatting, structure, images and videos to make the concepts you're explaining as obvious as possible.
2️⃣ Make it pretty
People use things that feel nice – this includes documents. It's not just about making things pretty though: using colours, formatting and emoji well make it easier to navigate and understand your document.
3️⃣ Keep it flat
Avoid splitting documents into multiple pages unless you have a good reason. Avoid deeply nested systems of headings unless you really need them.
4️⃣ Have things explain themselves
Documents should explain themselves. If someone can't understand what and who a document is for and how it works quickly, they'll have to waste time reading it before they can judge if it's what they're looking for. And if you link to somewhere else and it's not obvious why, explain.
5️⃣ Build for the future
Consider the longevity of your document. If it's a piece of permanent knowledge, write it in a way that reduces the work of keeping it up to date. For example:
- Avoid time-specific phrases like currently or we are planning to or our recent project identified.
- Prefer role titles over names when referring to people (still correct when people change roles).
- So long as it doesn't reduce clarity, consider using generic terms for things that might change (eg. "CRM not Salesforce", "Password Manager not 1Password").
- etc.
Some Practical Tips 🖊️
That's principles out the way. Let's look at some practical rules and guidance for making your documents awesome 🚀
Writing style
We write our internal docs in an informal, conversational style. Try to imagine you're speaking out loud to someone and write like that.
The number one rule is don't stress. Quality writing is important, but actually sharing what you write is much more important. Perfection is the enemy of done. That said, here are some tips…
- Don't be fancy. Write for the layman. (Fancy writing is hard to read – if you want proof, just read any academic paper)
- Prefer short sentences with minimal commas. This might not feel as eloquent. But it will be more digestible. Which is a good thing.
- Consider using contractions like we'll over we will - it feels more conversational and friendly for people who subvocalise as they read.
- Avoid jargon, especially in documents that will be used outside your team.
- Prefer UK English, but don't worry too much about it.
- Avoid localised language and phrases – be inclusive. We hire from more than one area/country.
- Avoid acronyms unless they're widely understood by all the people you're writing for.
- If you use a phrase lots and it can be shortened, write it in full the first time and put the acronym in brackets; use the acronym thereafter.
- Use a spellchecker and proofread your doc. But don't obsess – done is better than perfect.
- Take the time to read back what you've written exactly once. We don't need a literary masterpiece but a few tweaks to some clunky paragraphs can make a big difference to reader comprehension.
- If English isn't your first language and/or writing is stressful for you, don't stress. Write like you're typing a slack messages and ask someone to read over it.
Don't: "The marketing Kanban is jolly simple to use... easy peasy. Just pop your task in and hit save then have a cuppa. Piece of cake, what ho 🧐🇬🇧"
eg. "The Asset Inspect (AI) team should be informed. When the AI team have replied..."
Structuring your documents
There are a thousand ways to structure a document, and choosing the right approach will depend entirely on:
- what you're trying to communicate (and why).
- who you're writing for and why they're reading your document.
- what you're writing about.
It's important that you think about these things when structuring your document.
Here are some prompts that might help with this:
- What information is your reader looking for?
- How can you help them find and fully understand it as efficiently as possible?
- Does your reader need to understand some background or underlying principles to make sense of what comes later? If so this should probably come first.
- Might some readers want to understand some background or underlying principles after they've got what they came for? If so this should probably come later.
- Can you invent some repeatable structures that help with comprehension?
- Background and The Why.
- How we do
x. - How we don't do
x. - Further reading.
- Where do people go for help on this? What might they get stuck on? Perhaps a FAQ is useful?
Eg.
A note on Artificial Intelligence
Notion has some pretty cool built-in AI tools, which can be super useful in helping you write good documents. Likewise, tools like ChatGPT can be a huge help – especially if you aren’t great at writing and/or English is not your first language. But be warned – all current AI writing tools tend to produce way more words than are needed. Good writing means conveying your message fully but succinctly, and AI is bad at this.
Half the value of writing is that it forces you to organise your thoughts and put yourself in the shoes of your readers. If you feed AI unorganised thoughts, it will produce well-written unorganised bollocks. And it will never understand your readers as well as you. (Not yet, at least)
Remember: word count is not the goal – don't make readers wade through AI-generated gumph. Instead…
- Use Conversational AI to generate ideas, expand on your thoughts, critique your ideas etc.
- Use AI to help you write better, but not to write for you. It’s great at…
- Fixing grammar, spelling & clunky wording.
- Generating draft summaries, extracting key points etc.
- Improving the structure, tone and formatting of your documents.
- Always edit AI-generated text.
Further Reading
If you want to learn how to format documents well in Notion, check out 
If you want more advice on writing style, pick up a copy of The Elements of Style by William Strunk Jr & E.B. White…
