April 2021 – Shekhar Gulati

Minimal Technical Documentation Every Project Should Have

In the last few months I have given a lot of thought on the minimal technical documentation that all projects should have. I consider it essential to building a quick understanding of the project and quickly onboard new developers. These documents should be maintained in the version control just like the code. The technical documentation should sit in the same version control repository as your code.

If your system is built using Microservices architecture and you use repo per service approach then it will be better to have one repository only for documentation. I prefer monorepo over repo per service. You can read more about Monorepo in a blog post I wrote earlier.

The documents that I consider essential are:

README.md
architecture.md
api.md

Software Architecture Document Template

Below is the template that I use to document software architecture. This is based on the experience I gained doing architecture and design work over the years.

If you prefer Google Docs then you can create a copy of the template. If you prefer Markdown version then you get it from the Github repository.