Skip to content

Documentation guide

This guide explains how to work with the dataLOFT documentation. The documentation is written in Markdown, built with MkDocs Material, and published to Codeberg Pages.

Setup

Prerequisites: Python 3.13 or later and uv.

git clone <repo-url>
cd dataLOFT-docs
uv sync

Start the live-reload dev server:

uv run mkdocs serve

The site is available at http://localhost:8000. Changes to any file under docs/ reload the browser automatically.

Adding a page

  1. Create the .md file in the appropriate directory under docs/.
  2. Add an entry to the nav tree in mkdocs.yml.
  3. Link to the new page from the parent section's index.md.

Writing conventions

  • Language: English.
  • Active voice, present tense. Address the reader as "you".
  • Sentence case for headings.
  • Backticks for code identifiers: RUN-DSP, rdsp-s3, mkdocs.yml.
  • Never conflate management services and data services. A connector is a management service. r-squared is a data service.

Diagrams

Use PlantUML with the C4 model for architecture diagrams and Mermaid for sequence diagrams, state machines, and other behavioural views.

For PlantUML diagrams:

  1. Write the .puml source in docs/assets/diagrams/.
  2. Export to a .png in the same directory: 
    java -jar plantuml.jar docs/assets/diagrams/your-diagram.puml
  3. Reference the exported PNG in the markdown page.

For Mermaid diagrams, embed them directly in markdown using a fenced code block with the mermaid language tag.

Architecture Decision Records

ADRs live in docs/architecture/09-decisions/. Name new files adr-NNN-short-slug.md.

Each ADR covers: Status, Date, Context, Decision, Consequences, and Alternatives considered.

After adding a new ADR:

  1. Add a row to the decision log table in docs/architecture/09-decisions/index.md.
  2. Add the file to the nav in mkdocs.yml.