Documentation

Every software should have documentation written for it. It helps users by providing instructions on how to use the software. Follow these guidelines to write good documentation.

What Is Documentation

Documentation in a software project is a manual that describes the architecture of the software and provides helpful instructions to the users. These instructions include an installation guide, how to use the software, and also guides to resolve common issues users might experience while working with the software.

Source: Pinclipart

Why You Might Want Documentation

Providing clear documentation is important because it saves a lot of time for the users, other developers in the team, and even sometimes for the developer who wrote the code. How?

• Users while using the software for the first time, might not know how to navigate within the software or achieve the intended functionality. Clear documentation comes in handy at these times.

• Documentation helps other developers or open source contributors(in case of open source project) who are working in the codebase to understand the code better and makes the development process faster and simpler.

• In case of a situation, where the developer took a break from the project for a brief period or when the codebase becomes larger, it might be hard for the developer to remember all the details without the help of documentation.

• Even If you developed a good product but not provided the necessary information to use it, users probably won't use your product.

Problems Documentation Helps to Solve

• Poor code quality
• Less user support
• Ambiguity
• Less team collobaration

How to Implement Documentation

• Documentation should be clear and concise and must be written in a way that is understandable by all types of users.

• First, define the scope of your documentation and explain only those topics that fall under the scope.

• If there is any other software or technology that is not part of your scope but serves as a prerequisite for understanding your documentation, add a new section at the beginning of the documentation such as getting started and provide references to the original documentations of those topics.

• Provide step by step tutorials whenever possible.

• Include the error messages one might encounter during the process and also explain how to fix it.

• Update the documentation whenever you change the underlying functionality.

• Follow a layout that is commonly used in other documentations.

• Use tools such as Docusaurus or GitBook to create documentation websites faster.

Common Pitfalls of Documentation

• Outdated documentation

• Unclear documentation

• Unusual layout

• Improper Hierarchy

Resources for Documentation

• O'Reilly - The eight rules of good documentation

• Open Source - write better docs

• Corilla blog - If your product isn’t documented it doesn’t exist