Where documentation lives

Documentation about our systems lives in four places, and the split is not arbitrary. Knowing it saves an argument in review, and saves you writing a page that will rot somewhere it should never have been.

This page states the split for readers. The authority is CONTRIBUTING.md in this site’s repository — if the two ever disagree, that file wins and this page is the bug.

The four homes

Home	Holds
This site	Anything spanning repositories, or describing the environment — access, environments, conventions. Plus the internal API reference, under reference/api/
A repository	Its own code and behaviour, its own ADRs, and anything you would otherwise retype: config, schemas, account IDs, commands. Link those; never copy them
Confluence MONE	People, process, ownership, and decisions with a social component — who to ask, on-call, owner lists
almamedia.cloud	Alma-wide cloud platform guidance. Needs a GitHub login, where this site and Confluence need only an Alma identity

Secrets go in none of the four. The authority above has the same split row by row, so read it there when you need the exact wording.

The line between here and Confluence is write access, not read access

This is the part people get wrong, so it is worth stating plainly.

Both this site and Confluence are readable by anyone with an Alma identity — Cloudflare Access covers this site, Atlassian covers Confluence. Read access does not separate them.

Write access does. Content that engineers maintain in pull requests belongs here, because a pull request is how it gets reviewed, versioned and kept honest. Content that non-engineers edit themselves belongs in Confluence, as does anything that changes for social rather than technical reasons — a team roster changes when someone joins, not when the code does.

So “who do I ask for AWS access” is Confluence, and “what does the generated AWS config look like” is here, even though a new joiner needs both within the same hour.

The line between here and a repository is scope

If a page is about one repository’s code, it belongs in that repository, next to the code, where the pull request that changes the behaviour can change the page in the same commit. Nothing else keeps documentation true.

If a page only makes sense across several repositories, no single repository can own it without going stale — so it belongs here. The repository map, the glossary and how the services fit together are all of that kind.

That leaves a third category: things this site describes but does not own, like the reusable CI workflows or the GitHub organisation configuration. Those get a short orientation page here that links out, and the detail stays in the repository that enforces it. A copy would be a second thing to keep in sync, and the copy always loses.

Decision records belong to the repository they affect

An ADR is written in the repository it affects, as docs/decisions/NNNN-kebab-slug.md. This site keeps only an index — title, date, status, link — so you can answer “what have we decided” without already knowing which repository to look in. The index must never restate a decision.

The one exception is a decision about this site itself, which has no other home.

A decision spanning several repositories goes in the repository with the most at stake, with one row in the index. It does not get copied into each.

The four page types

The sections of this site are Diátaxis, and a page belongs to exactly one:

Type	Answers	Title style
How-to	“how do I…”	verb first
Reference	“what is the value of…”	noun phrase
Explanation	“why is it like this”	noun phrase
Start here	onboarding paths	—

If a page is trying to be two of these, split it. A how-to that keeps explaining itself should link to an explanation page instead — which is exactly what this paragraph is doing.

Generated API reference is the one exception to “written by hand”: it belongs under reference/api/, produced from the service’s own schema, and is never edited in place.

Before you write a page here

Read CONTRIBUTING.md. It carries the house style in full — sentences, voice, terminology, wrapping — and this page deliberately does not summarise it, because a partial copy of a style guide is how you end up following the half somebody remembered.

One rule from it is worth knowing before you read anything else here: anything stale gets a :::caution callout naming what is uncertain, rather than quiet deletion. That is why several pages on this site open with one. A warned page is more useful than a missing one.