Good Documentation
👷♂️ Work in Progress 🚧
This article is developing. I am probably still piecing the fragments of ideas in the right places. Feel free to poke me on Twitter to finish this piece.
Documentation is a mental map
After working on various software projects, I pondered the concept of good documentation. Each software project is unique, and even software that shares similar architectures and functionalities may require a different set of documentation to point out the differences.
Documentation provides a mental map and a starting point for new users to interact with or modify parts of the software.
Tips
Here are a collection of tips that other developers are sharing on good documentation:
1. Start with writing self-documenting code
Having a self-documenting codebase that adheres to some form of coding guidelines can improve the readability and understandability of the code.
Some tips from Mike Cronin on writing self-documenting code
- Don’t use magic numbers; always give a name for numbers.
- Use clear variable names, avoid using acronyms as much as possible
- Refactor with tiny, named functions; Don't Repeat Yourself
2. Write docs with user-centric goals
Swyx reminds us to write docs with user-centric goals
- Think about the user profile of your readers
| Users | Goals |
|---|---|
| Beginners | get to success as quickly as possible, avoid/recover from mistakes |
| Intermediate | contrast with comparable projects, learn every API/option |
| Experts | keep up with changes and future plans |
| Contributors | How to contribute, how the project is setup |
3. Keep an ARCHITECTURE.md for open-source projects
Aleksey Kladov encourages adding an ARCHITECTURE.md file to describe the high-level architecture of the project. It offers a low-effort high-leverage way for other developers to contribute to the project as it gives them a better understanding of the project.
Documentation Tools
A collection of documentation tools:
Atlassian Confluence : Comprehensive tool to document project info, decisions and share knowledge among technical and non-technical members in the team. Comes with connectors to popular apps such as Github, Azure DevOps etc.
Azure DevOps Wiki: Most git repositories such as Azure DevOps, Github and BitBucket comes with wiki pages at repository level.
Swagger: Generate documentation for your API endpoints
Storybook: A UI component explorer for developing UI components in isolation and documenting component stories
readme.so: An editor to quickly add and customize all the sections you need for your project's readme