Introduction
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.
Code Owners - CODEOWNERS file contain resources who own specific module in the repository and who should review before PRs are merged.
Example CODEOWNERS file
Architecture Decision Record (ADR) - is a document that captures an important architectural decision made along with its context and consequences.
Style Guide
- 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:
- ADR template by Michael Nygard (simple and popular)
- ADR template MADR (more Markdown)
Sample document: timestamp-format.md
# Timestamp Format Contents: * [Summary](#summary) * [Issue](#issue) * [Decision](#decision) * [Status](#status) * [Details](#details) * [Assumptions](#assumptions) * [Constraints](#constraints) * [Positions](#positions) * [Argument](#argument) * [Implications](#implications) * [Related](#related) * [Related decisions](#related-decisions) * [Related requirements](#related-requirements) * [Related artifacts](#related-artifacts) * [Related principles](#related-principles) * [Notes](#notes)