Documentation for Developers

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)
  

Reference

• joelparkerhenderson/architecture_decision_record
• Solution Architecture Patterns

Sample Project Docs link