4 Elements of Effective Documentation in Software Engineering

Writing effective documentation is an essential skill for software engineers. Clear and succinct documentation helps users, developers, and maintainers understand and use the software correctly.

Here’s my opinion! While no one like writing and maintaining documentation, forcing yourself to write clear and helpful docs for your library/software, you also benefit your own work.

You have to see things from the user’s perspective and this can reveal some hidden or minor flaws. These could affect how the user sets up and installs your product, or how they interact with your api, or how your system is structured, or how they use your features in general.

Here are four points to consider when writing documentation:

• Clear and concise explanations of the software’s purpose and functionality. The documentation should state what the software does, why it is useful, and how it works. The explanations should be easy to understand and avoid unnecessary jargon or technical details.
• Detailed instructions for installation and setup. The documentation should provide step-by-step guidance on how to install and configure the software on different platforms and environments. The instructions should include any prerequisites, dependencies, or compatibility issues that may arise.
• Comprehensive documentation of APIs and libraries used. The documentation should describe the interfaces, parameters, return values, and exceptions of all the APIs and libraries that the software uses or provides. The documentation should also include examples, code snippets, and links to external resources that illustrate how to use the APIs and libraries effectively.
• Thorough explanations of the software’s architecture and design principles. The documentation should explain the high-level structure, components, and interactions of the software system. The documentation should also justify the design choices and trade-offs that were made during the development process.

A clear and logical structure is also essential for your documentation. There are many possible ways to organize technical documentation, and your team may have its own preferences.

However, if you need a good suggestion, I recommend the Diátaxis system, which divides documentation into four types: tutorials, how-to guides, explanations, and references. The following diagram illustrates this system beautifully:

Diataxis system describing how to categorise technical documentation by laying them into 4 quadrants. Taken from (diataxis.fr)

Do you have any tips on writing technical documentation? Let me know in the comments. If you enjoyed this post, please follow me for more content like this.