Skip to main content

2. docs-as-code

Date: 2025-11-26

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 onbuy

Consequences​

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