# Documentation for Developers

## Introduction

Documentation is key to any project's success. When team members move to different projects, the **[Tribal Knowledge](https://www.lucidchart.com/blog/what-is-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](https://www.writethedocs.org/guide/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](https://confluence.atlassian.com/jirasoftwareserver/what-is-a-board-938845235.html)** to keep tracking releases, milestones, features, and project status.

* **Roadmap** should include short and long-term goals.

* **Changelog** - Automatically [generate](https://github.com/crestamr/AutomaticChangeLog) changelog as part of the release process.

* **Style Guide** - Every project should have a coding style guide.

* **[Code Owners](https://docs.gitlab.com/ee/user/project/code_owners.html)** - [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) file contain resources who own specific module in the repository and who should review before PRs are merged.
  
  ***Example CODEOWNERS file***

  ![image.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1658820581846/DoLkdeBxg.png align="left")

* **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](https://github.com/joelparkerhenderson/architecture_decision_record)
  - Markdown Architectural Decision Records [template](https://adr.github.io/madr/)
  
  ***ADR example templates***
  
  Some ADR example templates on the net:
  
  * [ADR template by Michael Nygard](https://github.com/crestamr/docs/blob/main/adr/template/adr_template_by_michael_nygard.md) (simple and popular)
  * [ADR template MADR](https://github.com/crestamr/docs/blob/main/adr/template/adr_template_madr.md) (more Markdown)

  **** Sample document: [timestamp-format.md](https://github.com/crestamr/docs/blob/main/adr/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](https://github.com/joelparkerhenderson/architecture_decision_record)
- [Solution Architecture Patterns](https://github.com/chanakaudaya/solution-architecture-patterns)

***[Sample Project Docs link](https://github.com/crestamr/docs)***