Good Documentation

1 min read ⚑️Last tended 2 years ago
Seedling 🌱Planted 2 years ago

πŸ‘·β€β™‚οΈ 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.

Photo from Unsplash

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.


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
Beginnersget to success as quickly as possible, avoid/recover from mistakes
Intermediatecontrast with comparable projects, learn every API/option
Expertskeep up with changes and future plans
ContributorsHow to contribute, how the project is setup

3. Keep an for open-source projects

Aleksey Kladov encourages adding an 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

  • An editor to quickly add and customize all the sections you need for your project's readme

Further Reading

It makes my day when I see it.
←Diagramming ToolsHow I built a Theme Switcher based on Singapore attractionsβ†’
Walter Teng Β© 2023