The Art of writing technical documentation: A guide for Software Engineers
Importance of technical documentation
Whether you're building a tool, library or a standalone product, it's important to give your users a clean manual about how this thing can be used. Not only users, but documentation is a very important factor for prospective users who consider using the thing you're building.
Having clear, well-structured but also detailed documentation helps a lot. Oftentimes, users are attracted to the project but sometimes can spend a big portion of time trying to search through the documentation only to fall back to browsing the code (it is possible), which makes them angry. Sometimes they can drop using the project because they hit a wall that they are not able to overcome because of the lack of documentation.
This article is a great introduction for folks who are wondering how to write good technical documents or how to describe a project for other technical people.
Why software engineers should write technical documentation?
- Improved user experience - Providing clear and comprehensive documentation enhances the user experience of the project/tool. Software engineers who wrote the code are best positioned to explain how it works and what capabilities it has.
- Future maintenance - Documentation also serves as a reference for future work on the tool. Documentation is a knowledge transfer tool, which eases the onboarding process for engineers joining the project but also as a way to store detailed knowledge of the inner workings.
- Personal development - I think, this is the biggest advantage of all. Practicing writing helps improve communication skills and bring clarity to your writing and speaking as well. Writing also makes you a better software engineer. If you have to explain what you've built and how it works, you will naturally lean towards simpler solutions. It's hard to explain how complex things works, much easier if they as simple. On top of that, as you grow as a software engineer, naturally you will extend you scope of responsibilities. It's not rare for software engineers to move away from coding more and more as they progress in their development careers. Moving away from coding comes as an alternative to writing, as a Senior/Staff engineer you will be responsible for aligning ICs, teams and the organization and you do that by writing.
- Accountability and credibility - Good quality documentation shows the professionalism and commitment of the engineering team behind the project. Good quality, comprehensive, always up-to-date documentation signals that the engineers care for the user and care for the project to be used in a full capability.
Break down complexity
This is an overarching goal of technical documentation: to break down the complexity of the project into smaller, digestible chunks. Here's the approach you can use:
- Identify concepts that are the key to understanding the project: Start by deconstructing the technical topic into its fundamental building blocks.
- Start simple and build upon fundamentals: Structure your content in a way that introduces basic concepts first, then builds upon them with increasing complexity.
- Use examples, code snippets and real-world use cases: Make sure you translate the theory into practice with examples
Headings as a roadmap
- Clear: You should use clear and concise titles. Descriptive headings and subheadings should accurately reflect the content of each section.
- Structured: Hierarchical Structure: Organize headings in a logical hierarchy, creating a clear roadmap for the reader to navigate the information.
- Scannable: Format headings and subheadings visually distinct from the body text to improve scannability.
Visuals
- Integration: Don't randomly throw diagrams, always introduce or follow up with a story. Use the diagram first to induce curiosity in your reader. Explain first then show a diagram to reinforce the explanation and align the concepts.
- Clarity: Visuals should be clear, concise, and well-labeled. Avoid overly complex diagrams that might overwhelm the reader, use arrows or markings to guide the reader in what order the diagram should be read.
Focus on a value, ensure your explanations provide value to the reader, less is more and sometimes an image is worth a thousand words. Help readers understand the "why" behind the "how."
Choosing a platform
There are multiple platforms that can accommodate technical documentation. But it's important to choose based on a couple of factors:
- Who is the writer?
- Who is the reader?
- What's the topic of the documentation?
Answering these questions is crucial. Atlassian Confluence platform will be used for a different audience and project that open-source VitePress. You have to take into account all of the factors above as writing documentation cannot drag you down. It should be easy and reading should be intuitive. Do your research and understand the weak and strong sides of each solution.
A list of open-source documentation platforms
You can also consider a static site generator for building the documentation, however, it will require more work to set up and maintain. I can recommend one especially: VitePress. This project is used to build Logdy.dev homepage, documentation and blog pages. It was easy to set up, it's extensible and customizable.
There's of course a comprehensive list of paid services, but I'm not going to promote any, I have my favorites which I use professionally. If you're curious contact me (peter (at) logdy.dev). If you'd like to dive into research here are two useful links to start with:
A curated list of awesome documentation tools
Comprehensive list of static site generators
Diátaxis - A systematic approach to technical documentation as ecosystem
If you don't know Diátaxis I recommend you to give it a read. It's simple yet powerful. Diátaxis proposes an information architecture for technical documentation to be oriented around 4 blocks:
- Tutorials - a learning-oriented guidance of a tutor. The goal is for you to learn as you progress through the tutorial
- How-to guides - goal-oriented guidance through a problem. This is a solution-oriented piece that puts more focus on reaching a specific goal
- Explanations - an understanding-oriented chapter that should describe separate building blocks in depth
- References - a theoretical way to describe a topic without space for ambiguity
Logdy docs as an example
Diátaxis proved to be a great way to build documentation for Logdy, you can check it out yourself. 
Tutorials
Learning-oriented guides. I used tutorials to also showcase a scale of Logdy applications. Each tutorial is a short article that highlights Logdy's main features in an "example-driven" way. In my opinion, complex topics are best described using examples, that's why tutorials are ordered before any explanations or references.
Explanation
This part explains concepts within Logdy along with some examples. This chapter allows the reader to fully understand how the tool works and find out its use case.
Reference
This chapter contains CLI and Code references. No comments or ambiguity just straight facts about how things work and what you can use.
Common pitfalls
Knowledge bias
As an author of the project, you are biased with all of the knowledge about how it works. That can translate to missing relevant parts in the documentation. 
When you're writing a chapter about a new feature that just landed, your mind is full of all the edge cases, use cases and possible applications of it, there's a lot of noise in your thinking but you still make it through and put it on the paper. However, during that time you may miss some details. Always review and proofread what you wrote after you finish a piece. A good way to understand whether you missed something vital is to read the content later (a few days or even weeks). This way you let your short-term memory clear and change the context, which means you somehow minimize the knowledge bias. After reading what you wrote after some time
Plugin system
Writing technical articles and documentation can be a challenging task. Often times, when writing content you want to refer to a specific part, code or feature. The reality is that all of these pieces are subject to change over time. As your content library grows, it can become challenging to scan the whole content to find outdated pieces and update them.
This is where a dynamic plugin system can be handy. It works more or less like this: you create a piece of content, whether that's a paragraph or a widget and you are able to embed it anywhere within the documentation. This feature gives you the power to keep things centralized and simple to change. The outcome: content that is placed in multiple places can be updated only once.
Inconsistent style and terminology
Having inconsistent style or using different terms to describe the same thing impacts readability and overall can confuse readers. Try to come up with a specific style. Don't worry it will take some time until you get it right.
Neglecting user feedback
The more people read your docs, the more feedback you will get. Readers are a great source for potential updates and fixes to your docs, don't ignore it. Make it easy for users to submit proposed changes to the content. Sometimes they will even come with pointers on which sections need clarification or further development.