Documentation
As a software engineer (especially since I'm still a junior and often change organizations), I've come to understand that documentation is crucial for several reasons: it provides a foundation for comprehending the entire software project as a whole for many stakeholders.
Docs as a Code (DAAC)
Document as a Code (DAAC) treats documentation with the same level of seriousness as code. This meaning involves managing documents through version control and meeting documentation standards for consistency. Document as a Code includes collaboration, automation, and consistent documentation practices that can ensure documents are up-to-date, correct, and easily accessible to all developers on the team.
What to Write?
Audience
Identify who will read the documentation to tailor the content appropriately. Is it for end user, external developers who wants to use your services or internal developers who want to develop software? Create documentation according to who is reading it.
Objective of the Project
Describe the goals and what the project intends to achieve and what problems it solves.
Project structure
Outline how the project is organized for easier navigation and understanding.
API Documentation
This section should outline the key functionalities of the API, describe its endpoints, and explain the parameters and return types. It should also cover any authentication requirements or rate limits.
API code example
Provide a simple example to demonstrate a common API call, such as fetching user data or posting information to a server.
Module Documentation
This part focuses on the internal structure and functionality of specific modules within the project. Describe the purpose of each module, its interactions with other parts of the software, and any dependencies it may have.
Module code example
Include a brief code snippet that illustrates how a particular function or class within the module is used.
Issue tracker
Explain how issues are tracked and managed in the project.
FAQ
List frequently asked questions to quickly resolve common issues.
How to get support
Detail the ways users/developers can obtain help and support to understand the documentation.
Installation guide
Provide a step-by-step guide to installing the software.
License
Clarify the software's licensing information.
People who contribute
Acknowledge contributors and outline how others can contribute.
Effective Documentation Tools From My Experience
In my career I have used various tools for documentation, listed here in no particular order but with reasons for their selection:
- Confluence: It integrates smoothly with other Atlassian products and offering a cohesive development workflow experience.
- Google Docs: Its simplicity and effectiveness for collaborative features such as editing, sharing, and gathering feedback.
- Github Wiki: It provides a structured way to organize documentation with each repository hosting its own documentation, thereby enhancing accessibility and organization.
- Notion: For me, Notion is favored for its customizable templates, straightforward interface, and robust third-party integration capabilities.
- Docusaurus: Specifically designed for open-source software documentation, it features an easy-to-navigate standard template.
- Mintlify