2. docs-as-code

Date: 2024-11-01

Status

Accepted

Context

See the accompanying RFC 001, but we want a place to store engineering docuentation. We want to write markdown, and follow a similar process to writing code, and it resulting in a pretty web page at the end. We decided against using something like notion, confluence or google docs as this does not promote review of changes.

Decision

We discussed this in our engineering round table meeting but we decided github + markdown + docusaurus + cloudflare was the way forwards.

We are going to:

• store docs as markdown in this repo
• use the docusaurus framework to turn these into a website
• use github actions to build and publish the website
• use cloudflare pages to host the site
• use cloudflare zero trust to restrict it to people within assetreality

Consequences

• we get docs served at docs.assetreality.com
• we have a place to document engineering related processes, decisions, and system design
• there is a process to publish and change docs