Lyceum developer wiki

To guide you in writing and reading suitable documentation, we separate our documentation with different tabs at the top into different business areas. Within each tab, our internal documentation should ideally follow the Diataxis approach ⧉, meaning a separation into guides, tutorials, explanations and references. This might first seem like a more verbose approach, but eventually helps with structuring and finding texts.

Warning

Articles not sorted into the categories guides, tutorials, explanations and references tend to be outdated and might require updates.

The menu structure can be found in the mkdocs.yml file at the documentations root. The first level are the tabs, followed by the nested, collapsed menu for the left-hand side.

In general, we aim to write programme code which describes itself. In this documentation, we do not want to dive into tiny details and and stay a bit further from the implementation details.

Prose belongs here rather than in the monorepo. A README.md in the repository should say what a directory is and link to the relevant page here. Anything longer than that ends up duplicated and then wrong.

Writing a page

Add both the Markdown file under docs/wiki/docs/ and a nav entry in mkdocs.yml. MkDocs does not pick the page up on its own.

Headings, page titles and nav labels are sentence case: capitalise the first word and any proper noun, nothing else. See DOC-4.

Building locally

The wiki is not a uv project, so pull its pins in explicitly and build from its own directory, as CI does:

cd docs/wiki
uv run --with-requirements requirements.txt mkdocs serve

PlantUML diagrams additionally need Graphviz and a local renderer. See docs/wiki/setup-plantuml.sh. Hosting and access control are described in docs/AUTH_SETUP.md.