Tips for writing good documentation¶
Writing documentation is almost my day-to-day work as a software engineer. The reason why I write documentation is that good documentation can help my team understand the system better and it is like a knowledge-sharing process. One day if I am on vacation, my teammates can still gain the knowledge that they need from the documentation without asking me.
I know not every engineer likes to create documentation. Some engineers might feel that creating documentation is just wasting time because the system is changing fast. That said, the documentation will be outdated fast. Yes, maintaining documentation is hard, and need to spend resources on that. But, when you work on a large system, good documentation can definitely facilitate team knowledge sharing and avoid some repetitive questions from others. It can help to free yourself from the loop of answering questions.
The more you share, the more extra things you can create. That means when you share your knowledge with others to make them grow, you will save a lot of time. So, if you are working in a large complex system and the team is large, I do think investing in documentation is a good choice for your engineering team.
From my experience in writing documentation, I summarized the following key points for writing good documentation:
-
Know your audience: Understand your audience’s knowledge level and the specific needs of your audience. This will help you tailor your documentation to their expectation.
-
Define your message: Clearly determine the core message or purpose of your documentation. What information do you want to deliver? Understanding your message will guide your writing and help you stay focused. If you don’t define your message, sometimes, the content might be too rich and lose focus. With this writing style, your audience might not know what you want to deliver in the documentation. Ask yourself, what message you are trying to deliver when writing documentation.
-
Tell a story: Frame your documentation in a narrative structure that engages readers. Start by presenting a problem and then providing the solution in a logical sequence For example, When documenting a system, introduce the problem, present the high-level architecture, explain critical scenario workflows, and delve into API and database designs. This approach guides readers to understand the system from a big picture to detailed aspects.
-
Provide concise summaries: Instead of providing a lot of raw content to readers, help them summarize the content to give readers a quick overview and provide a link to the detailed content at the end, enabling them to find relevant information efficiently. This approach allows readers to grasp the main points quickly and explore further if desired.
-
Visualize with diagrams: Instead of presenting a large block of content, leverage diagrams, flowcharts, or other visual representations to convey complex information. Visuals make it easier for readers to grasp concepts and understand relationships between different elements.
-
Break down large documentation and create links: If you have extensive documentation, break it down into smaller, more manageable sections. Create separate documents for different topics and establish clear links or cross-references between them. This allows readers to access specific information quickly and navigate between related topics effortlessly.
