How to Write Documentation 📑
An extensive, 360° guide about crafting effective product, tech and company docs.
Organizing knowledge is one of my obsessions.
Today, this is a core part of my work as a writer, but even in my previous life, as a CTO, I invested a lot of energy into processes that enabled good, sustainable docs.
I have written many articles about this — but they mostly cover specific angles (e.g. design docs, or meeting docs), so I thought this was a perfect topic for the second of our guides.
In the past few weeks I've talked with a ton of tech leaders, read plenty of case studies, and reflected on my own experience about tech documentation. So here is what we will cover today:
🌟 Benefits of docs — these are non-trivial and crucial to understand.
🏆 How to write successful docs — strategies to craft useful docs and make people stick with them.
🏷️ Types of docs — we talk about product docs, design docs, specs, and code comments.
📌 Docs cheatsheet — we summarize all the advice into a few easy steps.
🔨 Tools — the five best tools for writing modern docs.
📚 Resources — additional readings and case studies to learn more.
Let’s dive in!
🌟 Benefits of docs
To every person I surveyed for writing this article, I always asked, at the end: are you happy about your docs? 100% of them said no. Literally all of them!
I have found that this is not (only) because people struggle at writing docs — it’s that they are generally confused about what those are useful for and how to use them.
Writing docs — of whatever kind — has many benefits:
💭 Help your reasoning — writing is thinking. Going through the process of writing a formal document helps solidify your reasoning and come up with a better solution.
⚡ Improve output — you can support your writing with previously created templates, checklists, and examples. These make the work lighter and lead to better results.
💬 Improve communication — it is easier to have good conversations about complex topics when these are backed by writing. You get more thorough reasoning and easier convergence.
📔 Future reference — docs naturally record decisions and can be used for posterity.
These benefits happen throughout the whole life of a project, from inception to release to future maintenance.
Now, I have found that most teams over-index on the future reference use case, while neglecting the first two. But writing docs only after the fact is like retrofitting unit tests to production code: not completely useless, but you miss out on a lot of value.
Also, writing docs at the end is genuinely harder than doing it gradually while the work is in progress. Artifacts like meeting notes and design docs are not only useful per se — they naturally turn into long-term docs, later, with very little effort.
Minimizing such effort is crucial to helping people keep up with docs. In fact, people are only going to create docs if the value from their use is perceived as superior to the writing effort.
Based on how this equation turns out, you end up either in a vicious or a virtuous cycle 👇