Introduction

We generally place more value on delivering working software than writing comprehensive documentation. With that said, there are certain cases where documentation is essential.

Any documentation we do produce should have a clear purpose and be kept simple, short, and to the point (just barely good enough to serve its purpose). It is important to realize that documentation, much like software, is not just written – it has to be maintained.

A useful mindset is: If the entire team was to be replaced by an entirely new team tomorrow morning, how’d that go?

README

Each individual application, library or service should contain a README that provides the following:

• What the project is/does (optionally also the motivation behind it).
• How to install and run the project.
• Usage instructions (how to use the project, run tests etc).
• Instructions on how to access further documentation (e.g. API docs).
• Anything in particular that should be considered when deploying the project.
• Any known shortcomings or flaws.

Project log

Keep a centralized document that contains important project-related information:

• System architecture.
• Technologies used.
• Operating procedures and backup routines.
• Universally relevant non-functional requirements.
• A list of intended users and their personas.
• The different environments (e.g. development, staging, production) including URIs, required configuration, and how to operate them.
• Primary roles, stakeholders, and contacts.
• Write down important decisions and motivations behind them, agreements with stakeholders, and reasons for doing things certain ways.

Don’t neglect the last item. Those are things that will be forgotten or missed as people come and go. Understanding why you opted for library X instead of Y, or why a service was designed in a particular way, can save a lot of time later down the line.

Code

Don’t go overboard. There’s no need to state the obvious. Focus on the parts of the code that are not intuitive. Code in and of itself is generally sufficient to explain the “what”. Instead, add comments when the “why” is unclear.

Use docstrings or equivalent to document what a function or class does, its parameters, return types, and any exceptions it might raise.

Meeting logs

Write a quick summary of every (meaningful) meeting and keep it somewhere accessible. Information from meetings that is not recorded has a tendency to be forgotten or be misquoted later. It is also a good way to keep people that were not able to attend informed.

You can use the following template:

• Date and time.
• Who was invited and who attended.
• Agenda.
• Key decisions and other outcomes.

API documentation

API documentation should always and without exception be automated. Never ever should anyone be writing API documentation manually. Doing so is extremely time consuming and manually written API documentation is nigh on impossible to maintain.