Documentation for Developers

Documentation for Developers


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.

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:

    Sample document:

    # Timestamp Format
    * [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)


Sample Project Docs link