The projects that I join tend to fall into two categories: either they have no documentation at all (not even a README) or the documentation is composed of lenghty Word documents mainly filled with placeholders and sections pasted from other documents.
- Documentation should be colocated with the code
- Favor a format that can be edited without dedicated software and viewed easily on different platforms (such as Markdown for example)
If required you can write more extensive documentation in a knowledge management system. Link to it from your repository.
Ideally a new team member should be able to run a system without any assistance. The root of the repository should contain a README.md file containing:
- The prerequisites required to run the system
- The configuration (including secrets)
Ideally this would be automated so a new developer would only need to run a single command to get their environment up and running.
You can provide additional information, either in README or in a knowledge management system:
- Links to build and release pipelines
- High level architecture and flow diagrams
- Environments
Describe the implementation details for parts of the system that are important and / or complex.
An Architecture Decision Record is a short text file. Each record describes a set of forces and a single decision in response to those forces. The concept was introduced by Michael Nygard.
- Decision Log, Code and Development Environment by Simon Brown