Documentation is key to any project's success. When team members move to different projects, the Tribal Knowledge will be lost, and it would be hard for new maintainers to keep the project on track as per the original Roadmap. Let's follow Docs as Code philosophy and keep related documents close to code in the same repository.
Recommended minimal documentation for each project
Docs should be organized under the
docs folder at the root of the repo.
Readme File - Should contain project goals, big picture, list of features, and developer's workflow to contribute to the repo.
Project Boards to keep tracking releases, milestones, features, and project status.
Roadmap should include short and long-term goals.
Changelog - Automatically generate changelog as part of the release process.
Style Guide - Every project should have a coding style guide.
Example CODEOWNERS file
Architecture Decision Record (ADR) - is a document that captures an important architectural decision made along with its context and consequences.
- This folder should contain all ADR docs
- We followed ADR file name conventions from Joel Parker
- Markdown Architectural Decision Records template
ADR example templates
Some ADR example templates on the net:
Sample document: timestamp-format.md
# Timestamp Format Contents: * [Summary]( ) * [Issue]( ) * [Decision]( ) * [Status]( ) * [Details]( ) * [Assumptions]( ) * [Constraints]( ) * [Positions]( ) * [Argument]( ) * [Implications]( ) * [Related]( ) * [Related decisions]( ) * [Related requirements]( ) * [Related artifacts]( ) * [Related principles]( ) * [Notes]( )