Company Docs 📖

How to create long-lasting documentation for your team and your company.

Hey, Luca here! 👋

This is a ✨ special edition ✨ of Refactoring for free subscribers! This article was originally exclusive to paid members, but it got really popular 🔥 so I thought of opening it up to everyone.

As always, if you want to receive one of these every week, consider subscribing.

Here is what you missed this month:

• 🗓️ How to Spend Your First 90 Days

• 💼 How to Create a Good Hiring Process

• ✨ Product Engineers

---

For decades, companies created documents that fell under a few, rigid categories: spreadsheets, text, presentations.

We did so with Microsoft Office and we do the same, more recently, with Google Docs.

These tools propose a model of the world where you create every time a single document for a specific purpose. Everything you need should be in that document, with little connection to the others.

This model was inspired by real, paper documents. You write and share them with people, physically, each on its own.

In recent times, new tools rose to propose a different approach. Notion, Coda, and the likes, focus more on the relationships between documents than documents themselves. They help us create a body of knowledge that is dynamic and connected.

While Microsoft Office was inspired by paper documents, these tools are inspired by Wikipedia.

In other words, while the old generation of tools is skeumorphic and mimics reality, the new one is, finally, internet-native.

This brings benefits both to companies and individuals:

• For individuals — it changes how we can learn new things and connect them to our existing knowledge. It allows us to create second brains for ourselves.

• For companies — it changes the way people work together. Information is not siloed anymore, you connect different pieces of information to generate insights and improve collaboration.

In the past I have talked about my own writing and note-taking. Today, instead, I will take on the perspective of a company that wants to build strong and long-lasting docs.

I will do so because I am passionate about this topic. I have been the "documentation guy” everywhere I have been, lived the transition between different tools, and failed multiple times before settling with something that worked.

We will talk of:

• 🟢 Why you should write

• 🔴 Why documentation fails

• ⭐ Documentation principles

• 🏃‍♂️ How to get started

• 🔨 The 5 best tools to write docs today

• 📚 5 examples and guides

I will write guidance that is not related to any specific tool or structure. Even though I do have my own tool preferences (which I will tell), I believe some ideas are universal and can be applied to any setup you may already have.

So I will try to strike a balance between being general — with principles, values, and theory — and practical — with examples, tools, and case studies.

Let's dive in! 👇

🟢 Why you should write

Staff meetings at Amazon begin with 30 minutes of silent reading.

The purpose and agenda of each meeting is written down in advance on a 6-pager. Participants read it silently at the beginning of the meeting.

Quoting Jeff Bezos:

When you have to write your ideas out in complete sentences and paragraphs, it forces a deeper clarity.

Writing down six pages of content is no easy feat, but it allows everyone to get deeply up to speed.

Written information brings several benefits:

• 🔄 Reusability — by writing something once you make it available to everyone who will need it in the future. People, in turn, may also take what you wrote, improve it, and evolve it into something better.

• 🔀 Asynchronicity — written information doesn't need everyone to be present at the same time. It allows people to consume content when it's best for them, optimizing their work.

• 🔼 Reflection — writing something down requires more thoughtfulness than just speaking your mind in a meeting. Higher quality information leads to better alignment and higher quality decisions.

Although these are clear and desirable qualities in any team, many companies struggle to create long-lasting, up-to-date documentation.

Why is it so?

🔴 Why documentation fails

Writing a thoughtful document is hard work. This effort is supposedly repaid by the document being read and used in the future.

If the value of future use is perceived as inferior to the writing effort, people are not going to write. It's that simple.

When this happens regularly, we have a vicious cycle:

1. People don't write docs because no one reads them

2. Docs become partial and outdated

3. People don't trust and read docs anymore

Viceversa, a good documentation process ignites a virtuous cycle:

1. People write more docs because they feel they are valuable

2. Knowledge grows larger, more insights are discovered, decisions are taken faster and better

3. People read more and more docs instead of having meetings

How can we avoid the former and create the latter?

⭐ Documentation Principles

Documentation is a game where players are, in turn, either readers or writers.

• As a reader — I want to easily find and read valuable information about what I need.

• As a writer — I want to easily write about what I am working on and contribute to the company knowledge.

In both cases, we want to minimize effort and maximize value. So, without getting into any particular structure or tool, these are the qualities we should optimize docs for:

🔄 Reusable

Design your notes to be easily reused and connected.

The more information is reused, the more value it provides and the easier it repays the cost of writing it.

For reusability, the best strategy is to have notes that are small and cohesive. Create a note around a single concept, and link it to all the other notes where this concept is mentioned or useful.

The best docs I have ever found are all densely connected. Be they personal, like Andy’s notes, or professional, like the GitLab’s Handbook.

🔍 Discoverable

Make content easy to be found.

Whatever tool you use, create a simple structure and avoid excessive nesting. Prefer tags (if you can) to deep subfolders, and make navigation as easy as possible.

Discoverability works in two ways:

• For readers — the easier people are able to find content, the more they will use it.

• For writers — the easier people understand where notes should go, the less the cognitive effort is required to create new ones.

💡 Example: For their internal docs, Notion has ditched folders in favour of a global database organized with labels.

🍱 Contextual

Organize notes around how you will use them.

Think at what they are useful for, in which situations you will need them, and put them there.

For example, you can usually separate between area notes and project notes.

• Area notes — evergreen documentation about a specific area. E.g. engineering onboarding, database schemas, company org chart.

• Project notes — docs you need to deliver a project. They may span multiple areas for cross-functional teams. E.g. product requirements, designs, roll-out plan.

Also, the context changes over time. Project notes may move into the respective areas after the project is delivered.

💡 Example: The PARA method by Tiago Forte is focused on actionability and is great for organizing both personal and professional information.

📦 Archivable

Archive what you don't need anymore.

Make sure you have a safe place (e.g. an archive folder) where you can put notes that are not useful anymore.

Keeping your space decluttered is crucial to keep signal-to-noise high and maintain people's confidence in using your docs.

🤗 Supportive

Guide people through the usage of documentation.

Do your best to reduce the learning curve and the effort to use documentation.

• Create an onboarding area that explains how documentation works.

• Create templates for recurring types of documents (e.g. meeting agendas, projects).

💡 Example: GitLab's handbook, used internally to run the company, has a 5000+ words page on how to use the handbook itself.

🏃‍♂️ How to get started

Consider the Gall's Law:

A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over with a working simple system.

Documentation may eventually become a complex system but, at the beginning, make it simple and write down only what matters.

For each area or piece of content, focus on:

1. 👁️ Purpose — reflect on how you will use what you are going to write. If you can't find a practical answer, scrap it.

2. 🏅 Ownership — define who is in charge of writing and keeping that information updated.

3. 🎒 Process — attach the creation of docs to existing processes. E.g. create meeting notes for each meeting, or project docs for each new project.

---

And that’s it for this week! Before we get to the resources, if you liked the article, consider doing any of these:

1) Share it ❤️ — Refactoring lives thanks to word of mouth. Share the article with someone to whom it might be useful.

2) Leave a comment 💬 — or a question, or simply your take!

3) Subscribe to the newsletter 📬 — if you haven’t already!

---

🔨 Tools

Here are the 5 best tools I know of for creating modern company documentation.

1. Notion — the most popular modern tool to create knowledge bases, workflows, and organize work and life in general. It is hard to even define what Notion does, as it replaces so many tools. It is my favourite and has a great ecosystem around it.

2. Coda — close to Notion but slightly more techy. It also boasts integrations with popular tools like Github, Gmail, Intercom, and more options to build workflows and internal tools. A fantastic all-round tool.

3. Slite — while Notion and Coda are as much about knowledge as they are about workflows, Slite is more focused on knowledge. It provides a beautiful canvas to create and organize written content, and plenty of collaboration features.

4. Slab — closer to Slite than to Notion or Coda, it also includes deep integrations with Dropbox, Google Drive, Slack, to surface content from all of your sources. It is an interesting take and a good option for companies who have already invested in other doc tools.

5. Confluence — this list wouldn't be complete without the flagship Atlassian product. If you are into JIRA and the whole Atlassian ecosystem, Confluence is a solid choice for your documentation that ties in with the rest of our workflow.

📚 Readings

• 📑 How Notion Uses Notion — even if you are not into Notion, this is a great read into how a 100+ people company organizes their knowledge. It is rare to find such in-depth case studies, and this one is really good. Also, most advice is general and applicable to any tool.

• 📑 Writing Culture at Amazon — famously, Amazon ditched presentations in meetings in favour of written memos that everyone has to read in advance. Rahul Ramchandani collected stories by ex-Amazonians about this. A fascinating read.

• 📑 The PARA Method — by Tiago Forte. It is the best framework I know of for organizing digital information. I use it both for life and work.

• 📑 GitLab Handbook — this handbook is the central repository for how GitLab is run. GitLab is 100% remote and global, and people literally work and coordinate through the handbook. It is more than 2000+ pages and includes vast documentation about how the handbook itself is managed.

• 📑 Slab Library — tons of examples of internal documentation from successful companies like Coinbase, Basecamp, Netflix and more. Check out Trello's remote policy, how Netflix runs code reviews, or Salesforce's meeting agenda template. It's a great resource.

• 📑 Notion Guides — the Notion's guides section is the richest I have ever found about writing internal docs. It includes high-level advice, workspace templates, and case studies from other companies.

---

How would you rate this article? 🤔

Amazing • Great • Good • OK • Meh