In my 25 years of experience as a developer, the only documentation that survives is the one in the repository, next to the source code.
Anything outside the source code repository dies a slow death as soon as 2 or 3 members of the team get replaced, which happens quite often.
Here’s my recommendation to tackle that:
1 – Create a few high level diagrams using PlantUML, maybe some higher level C4 architectural diagrams of the system. Do not go too deep here. This has to be the stuff that will almost never change.
It’s very important to document external dependencies, so that anybody joining the team can immediately see what they are. This is extremely useful when you’re called in to troubleshoot a nasty production issue.
Very important: Store the *.puml files in the source code repository and version control them just as you do code (they’re text files after all).
2 – Use Open API / Swagger for the APIs. The explanation about the inputs and outputs from the API endpoints is added directly in the source code. In java that is done via Annotations, I’m sure other languages have their way of doing it as well.
This automatically generates a page with a detailed view of all the APIs.
3 – For Text based explanations, like for instance the Ubiquitous language (a doc explaining the business terms), I recommend using README files, also stored in the source code repository and version controlled there.
But once again, focus on stuff that will almost never change.
For stuff that often changes, forget about it, you will never keep it up to date, so there’s no point in creating docs for that. Focus instead of having a source code that is very easy to understand, you might even have peer review sessions with the group towards making the code simpler to understand, removing magic numbers and unnecessary patterns.

Leave a reply to Using the code repository as the project management tool – Flavio Pezzini – Senior Developer Cancel reply