ADR-003 - Technical Documentation

Status	accepted
Date	2025-04-01
Decision Makers	Dardan Bujupaj (AX)

Context

We need do document the architectural design and decision of the application as well as the technical implementation details.

Decision

We will use Markdown documentation to document the architectural design and decision of the application.

Documentation language will be english, as this is the preferred language for technical documents at Griesser.

Starlight will be used as a documentation framework for now. This enables us to deploy the documentation as a static site. The Markdown documenation will be written in a framework agnostic way, so it can be easily migrated to another solution.

We will use Mermaid for creating diagrams and flowcharts. This allows us to easily visualize flows and relations in code.

Consequences

• All documentation will be written in markdown.
• Documentation will be published as a static website in Griesser Azure Cloud environment

Alternatives

• Use Azure DevOps Wiki: Not as flexible as markdown and readers need access to Azure DevOps.
• Use specialized Documentation software: Additional features are not needed for our use case.
• Use MkDocs: More mature than Starlight, but more effort to get a good looking documentation. As we use markdown, we can easily migrate to mkdocs in the future if needed.
• Use C4: This is a more sophisticated approach to visual architecture modeling but less flexible than mermaid. Also would need additional tools and steps to make the diagrams embeddable in the documentation.