Lean Documentation

This page is part of 🧰The Toolbox by Danny Smith.

One of the principles in 💡Asynchronous Working is Document Everything.

Let’s dive a little deeper into that…

Why is documentation so important?

If you're like most people, you probably asked someone in person or picked up the phone. This works fine in synchronous teams, but in an async team there might not be anyone around to ask.

This is why it's really important for async teams to write and maintain good internal documentation.

What does good documentation look like?

The internet is full of articles on how to write well. Much of the advice out there is good, but for our purposes we'll stick to three properties of good internal documentation:

1️⃣ Clear & concise

Keep docs short and to-the-point. They are not meant to show your editorial skills – they're there to convey information fast and clear.

Avoid superfluous words that don't add anything, and strive to make your meaning clear in as few words as possible. Keeping something clear and short can be quite hard, but you should try.

2️⃣ User-focused

Put yourself in the shoes of the person using your document. What will they need to know? What questions will they have?

Do your best to make it easy to use – headings, diagrams, bullets, checklists, videos etc.

3️⃣ Interconnected

Good internal documents should almost always be linked to other relevant places. If you mention a google doc, or notion page or slack channel link to it there and then. This makes it much easier for the user to understand your document.

Note: It's usually better to link to other documents, rather than copy/paste content from them.

What should I include?

Most good internal documents will include:

• Why - a brief explanation of why the document exists.
• What / How - The main contents of the document.
• Where to find more - Links to places where the user can find out more or ask questions. This might be as simple as: Message Kirki on Slack if you have questions.

How to Write Well: 4 Steps to Improve Your Writing

"There is nothing to writing. All you do is sit down at a typewriter and bleed." - Ernest Hemingway Introduction Looking back, I always struggled with writing. I felt pain every time I try to fill a blank page. I could bear the pain of writing in high school, but I almost gave up in...

adamfaliq.com

"Lean" Documentation

Creating new docs can seem daunting or time-consuming but it doesn't need to be. Most documents evolve over time. We can think of this iterative process as "lean" documentation. We'll start with something simple and gradually improve it as necessary over time.

Here's an example of a process you might go through when creating some internal documentation:

1. Finish a piece of work.
2. Record a Loom video explaining it.
3. Embed it in a page in Notion with a one-paragraph explainer about why.
4. Link any snippets, diagrams, other notion pages that might be useful.

Here's an examples of a document created like that...

This is a good first version, and is really quick to do. If a lot of people start using the document, we should consider expanding it a little by:

• Transcribing the loom video into written form, perhaps with some screenshots.
• Adding some headings, checklists etc.
• Expanding the text to provide more context.
• Including extra information, such as special cases.

Here's what the example might look like if we did that...

We could continue to iterate on the document in the future. Here's what it could end up looking like after a little while...

The key point here is that having a fairly short but useful document is much better than having no document at all. We can always iterate to make it even more useful in the future.