How to write good technical documentation

In the realm of software engineering, documentation holds a position of utmost importance. As software systems grow in complexity and scope, relying solely on the ability to retain information in one's memory becomes impractical and risky. Documentation serves as a comprehensive and structured repository of knowledge, capturing the design decisions, implementation details, and usage guidelines of software projects. It not only facilitates effective communication and collaboration among software engineers but also enables seamless onboarding of new team members, enhances maintainability, and reduces the likelihood of errors. In essence, documentation is the backbone that supports the efficient development, maintenance, and evolution of software systems.

However, most programmers hate documentation, and documentation is nonexistent in some cases. Lack of documentation can cause avoidable conflicts that will repeat itself later down the road. Documentation is a necessary evil that can be worth it if done correctly.

Why developers hate documentation

Most developers do not read the documentation. Some examples include, not reading each page of documentation on each page or thinking it is a waste of time.

Here are a few reasons why developers hate documentation:

• It takes time to write documentation and it's not easy.
• Coding is better and more fun.
• We have deadlines to deliver the code.
• Nobody reads the documentation.
• Need to maintain it and becomes forgotten.
• Don't know what the code does.
• Too lazy to write documentation.

How do we as developers improve writing documentation? There are so many questions I ask on how to improve my technical writing skills as a developer.

One of the main reasons I started blogging was to improve my writing skills.

Differentiating “useful” vs “useless” documentation

There is a way to write effective documentation. Documentation is put into two categories – “useful” or “useless”. Documentation considered “useful” is something that helps the developer to gain the information that they are looking for. “Useless” documentation can be unrelated or not provide the developer with the information they are looking for.

How to write “useful” documentation:

1. Define who your audience is

Define who your audience is when planning documentation. What type of user is going to read the documentation?

2. The long part – documentation itself

I have written various forms of documentation from writing code comments, README for personal, getting started guides, and tutorials. I’m getting back into writing after taking a break for a couple of months. My tip is to organize the documentation by creating an outline. The outline serves as a guide when writing and it helps speed up the process.

3. Adding content

After writing the documentation, I will add code snippets or screenshots to convey more information. Adding visual content can be tricky and can make comprehension difficult if done incorrectly. For code tutorials, add code snippets and explain the code. Context matters, displaying visual content without any explanation.

4. Maintain documentation

Documentation becoming outdated is inevitable when a new change gets added. Deprecation is natural regarding software development.

Here are tips to maintain documentation:

• For releases, plan to update documentation detailing the latest changes.
• For larger projects, assign a person who will be responsible for updating documentation.
• Automate documentation maintenance by checking metadata, links, and linter.
• Deleting documentation is a tricky subject. When the documentation becomes outdated or not useful it should be deleted. However, this is not the case. I have seen older versions of documentation that are archived. If the documentation is set to be deleted, please notify your users of the changes and any updates made to the documentation.

Is there such a thing as “useless? documentation

In my opinion, the answer is no. Every documentation has its purpose. Some developers may write documentation for themselves. I call this type of documentation “developer notes”. It is more personal compared to writing documentation for a wider audience. Developers can write down a feature of changes they implement and use these notes later on.

Why developers should write more

In conclusion, documentation is a critical aspect of software engineering that cannot be overlooked or undervalued. It acts as a foundation upon which software projects are built and sustained over time. Documentation allows software engineers to effectively communicate their ideas, share knowledge, and ensure consistent understanding among team members. It serves as a guide for troubleshooting, debugging, and maintaining software systems, minimizing downtime, and improving reliability. By investing time and effort in creating comprehensive and up-to-date documentation, software engineers lay the groundwork for successful collaboration, efficient project management, and long-term sustainability. Ultimately, documentation empowers software engineers to build robust, scalable, and maintainable software solutions that meet the needs of users and stakeholders.