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:

1. README.md
2. architecture.md
3. api.md

README.md

README.md is the first file that people interact with when they look at your project source code. I still find projects where README is essentially empty or it does not exist. README.md gives a perfect opportunity to the development team to explain their project to others or future developers who will be joining their team. The details that I look for in the README.md are:

1. High level overview of the project. In 3-4 explain what this project does
2. Project CI and quality badges 
3. Requirements. Programming languages, Tools, etc required to be installed on the machine
4. Build instructions
5. Running local instructions. This should cover both the dockerized version and step by step running instructions
6. Configuration. Any configuration that could be useful for the developer like changing port number
7. Links to important services
   1. CI server like Jenkins, Github Actions, CircleCI
   2. Project management tool like JIRA
   3. Prototyping tool like InVision

architecture.md

This file should describe the high-level architecture of the project. You should share this file with anyone who wants to understand the technical details and architecture of the project. This should have the high level architecture and details that don’t change often. If you use the C4 model to document your architecture then this document should only have context and container diagrams. I store this file in the project root docs directory.

The minimal details that I look for in architecture.md are:

1. Constraints. Any business or technical constraint that you had while you designed the system. You need to call out these constraints and how they influenced the design.
2. Non-functional requirements. Most important quality attributes required to meet the business goals.
3. Architecture style. Based on the quality attributes which architecture style meets the need. 
4. Solution context diagram. This is a high level context diagram that shows system as a black box, its main user personas, and external integrations
5. Solution container diagram. You create the solution diagram showing different components that make the system. You should call out if it is a library or a service.
6. Technology stack along with versions. The list of important technologies that you use to build the system and the reason you choose them.

Diagrams should also be stored as code so that it is easier for people to change when required. The documentation should also follow the code review process just like code. There are not many good diagrams as code solutions. I version control Draw.io JSON files.

api.md

api.md documents the external facing API of the project. This is usually a REST API but it could be GraphQL as well. Most teams use Swagger to document REST APIs. Swagger documents are written in either YAML or JSON format. The JSON and YAML are not easily readable documents. I use a tool called swagger-markdown to convert a Swagger document to a markdown document. This file is automatically generated each time a Swagger document is updated. 

Conclusion

Well documented README.md, architecture.md, and api.md can take a development team a long way. You can onboard new developers faster and communicate your architecture and design effectively. The other positive impact of good documentation is that it saves a lot of time as people can read it themselves. I also think development teams can keep half a day every 3-4 sprints to revisit the document and make any revisions if required. Good documentation is the cost effective way to scale engineering teams.