10 Best Practices For Writing Documentation

Documentation is written data or instructions that outline a certain problem statement, approaches, functionality, workflow, architecture, challenges, and development process. Documentations can be used to gain a comprehensive understanding of the solution’s functionality, installation, and configurations at once.

Writing good documentation holds immense significance in the world of software development. In this article, you will get the significance of a documentation process and 10 tips and best practices to write better documentation. This article will also touch upon recommended tools and websites for creating good documentation. 

Now, before getting into the tips and tools let us first know the importance of clear documentation for a software development cycle, 

Importance of a Good Documentation

Here are some points to debate, the importance of writing good documentation,

• You are Your First Audience: Contrary to popular belief, documentation is not primarily written for other people. It’s for ourselves to know what we’ve done previously, which helps us catch on to the exact mindset and thoughts while we are developing them.
• Increase in Productivity: Well-documented programs allow team members to collaborate efficiently, reducing the time a team spends figuring out how to perform tasks and making them follow the established workflows.
• Clarity and Understanding: Documentation gives us the power to review the function and logic of a particular piece of code. So, that it could help both you and others to understand the implementation details which makes it easier to maintain or debug the program.
• Knowledge Transfer and Onboarding: In a company, documentations play a valuable role as it can cut down hours of knowledge transfer for new team members or developers joining the project.
• Enhances Code Reviews: Documentation will make the code review process simpler and more efficient because the reviewer can simply go through the documentation to check the logic and implementation.

How to Write Better Documentation – 10 Best Practices

Now, let’s see how to write good documentation and what practices you should follow to write high-quality documentation. Here, we have explained a small problem to create an API (API that returns unique cat images on every call) wherever it’s necessary. 

1. Start with the Problem You are Trying to Solve

Explaining the problem is like setting up the stage, and understanding the problem before developing a solution. This gives us a deep understanding of the problem itself and writing them down will consciously open up the possibilities to develop an efficient solution. Clearly defining and articulating the problem helps you identify the root cause of the problem and its potential implications. It also helps to communicate the problem with others, such as team members, reviewers, and other potential readers of the documentation.

Here is the comparison of articulating the problem in a good way and a bad way,

Good Way

Bad Way

Problem Statement: Our objective is to create an API that, in response to a request, always returns a different image of a cat. The API should make sure that the images returned are unique and do not repeat. This API is intended to be used in various applications for entertainment and for fun. Note that the client particularly requested to develop the API keeping in mind that in some cases the API will be hit by a large number of requests at a time. So, the API needs to be developed keeping this into consideration.

Problem Statement: To develop an API to return Cat Images.

2. Know Your Readers

When it comes to writing good documentation, one of the key things we need to consider is understanding who your readers are, and writing accordingly. Just like a skilled writer tailors his work to their intended audience, it is very important for a developer to write the documentation by understanding the reader’s potential. One of the ways we can do that is by using certain languages and terminologies which will be easily understandable and graspable by the readers. 

For example, your reader can be a project manager or a stakeholder, or another fellow developer. The level of detail of the documentation should be easily adaptable by the intended readers.

3. Document Your Decisions Going Forward

The ideal time to use this tip is when you are going to take a break from coding, but you need to make sure that you remember the flow of your project. For example, the logic, design, and architectural decisions you make. It is crucial to track the decisions or choices made by you in the past while capturing the journey of the particular development. This will greatly help you to catch on to the exact mindset or state after your break. The decisions need to be tracked with suitable justifications (Why you made the choice?). Here is an example of that,

“Decision: We opted to integrate a PostgreSQL database for efficient data storage.

Justification: PostgreSQL emerged as the ideal choice due to its robust reliability, scalability, and extensive set of features. The database’s ACID compliance guarantees utmost data consistency and integrity, a paramount aspect for the success of our project. Additionally, PostgreSQL’s exceptional support for advanced querying capabilities and its extensibility empower us to seamlessly handle and analyze vast volumes of data.”

4. Document Important points

Documenting important points refer to tracking all the reference links, documentation, and research sources so that it is easier for the developers to access the resources quickly and easily rather than searching for specific documentation or resource for a long time. This can save hours of time if implemented properly. We have to emphasize more on preserving the vital details for future reference as it has the ability to save a lot of time on developing, maintaining, and even updating the version of the particular code.

“IMPORTANT LINKS:

fastAPI Documentation: https://fastapi.tiangolo.com/

Postgresql – Python documentation: https://www.postgresqltutorial.com/postgresql-python/ ”

5. Keep it Simple, Clear, and Self-Explanatory

Documentations should be easily understandable by the readers. We have to explain the functionality and logic used to build a module very clearly, which helps in further development, maintenance, and upgradation of the module. We have to keep the documentation as clean and organized as possible. Making the documentation itself self-explanatory is crucial. While documenting a complex part of the program it is recommended to add sample codes to the documentation and really try to break down the code and make it clear for the readers is vital. As we have discussed earlier your documentation is going to reach a wide range of people so, it is very important that your choices of words and structure of the documentation be clear and display a sense of clarity to the reader.

6. Documenting is a Shared Responsibility

Creating and maintaining documentation should not be a sole responsibility. The effort to create documentation should be crowdsourced for a number of reasons, Primarily, to distribute the workload of an employee this allows all the other contributors to show a sense of ownership towards the project.  Involving contributors from different departments or domains will allow us to create holistic and well-rounded documentation.

For example, A developer may contribute to the technical insights in the documentation while the business stakeholders provide the goals and future aspects of the project. Overall, crowdsourcing the documentation effort allows you to tap into your team’s collective knowledge and expertise, resulting in more extensive, accurate, and widely acknowledged documentation.

7. Follow a Uniform Format

We need to follow similar formatting techniques throughout the whole documentation to make sure it is easily understandable and it allows the readers to easily navigate the content and get useful insights efficiently. We have to properly format the document using headings, sub-headings, points, and tables if necessary. These allow us to maintain the readability of the documentation.  By adhering to a uniform format, we can able to create cohesive and user-friendly documentation. For example,

Modules of API:

• Authentication Module
• Image retriever Module
• Request & Response Module
• Utility Module

Authentication module

# about the authentication module

Image Retriever Module

# about image retrieval module

8. Add Diagrams and Visuals

Including diagrams and visuals in the documentation can greatly improve the understanding and engagement of the readers. It is easier to explain complex logic and implementations visually. Visual representations like diagrams, flowcharts, and graphs help to illustrate processes, systems, or data in a clear and concise manner. Visual representations like these serve as a universal language that can overcome the barriers like language proficiency or technical expertise. While incorporating diagrams make sure to add clear and concise labeling and maintain consistency to avoid unnecessary confusion for the readers. Always keep in mind that graphics should enhance written content rather than completely replace it. They should be used sparingly, with a focus on more efficiently communicating complicated or significant information. For example

9. Start the Documentation Work Alongside Development

Often people write the documentation after the development phase which is a common misconception and a bad practice, this not only makes the documentation phase more complex but it also leads to a lot of wrong information in the documentation. In this case, it becomes challenging to recall important information and details of the development phase. Furthermore, the creation of documentation post-development increases the potential for misconceptions and misunderstandings to proliferate. Without real-time documentation, developers may resort to personal interpretations or assumptions, resulting in inconsistencies between the actual implementation and the documented information.

10. Review Your Work at the End

Finally, in the end, the process of writing documentation involves reviewing the documentation thoroughly. Till now we would have not worked on the documentation continuously because we would have been involved in development and documentation to and forth, which makes this a vital part of creating documentation. There is a possibility that our documentation lacks the structure it needs. Finally, tweaking some things and restructuring the documentation can make it a well-formatted and comparatively better documentation.

Tools and Websites For Creating Documentation

When it comes to creating clear and self-explaining documentation, different tools and formats can be used depending on your audience and the purpose of the documentation. 

Here are some of the websites people in the industry use in common:

1. GitBook – Free and easy-to-maintain versions of documentation
2. Read the docs – More complex setup, good for technical documentation 
3. Document360 – Expensive but covers all the necessary features

To Create Diagrams and Flowcharts, you can use:

1. Microsoft Visio
2. Whimsical

Conclusion

In conclusion, every developer should have a firm grasp of the craft of writing documentation. You can enhance the caliber, precision, and efficacy of your documentation by paying attention to the ten suggestions offered in this article. Keep in mind that documentation is a useful tool that improves productivity, cooperation, and knowledge transfer rather than merely being an afterthought or a routine task. So, start your road to being a master documenter while embracing the humor and obstacles.