Documentation

Writing the documentation

The docs live in this repo under docs/, one MkDocs site per directory, each with its own docs/ of markdown and its own mkdocs.yml:

site	audience
zf-general	Anyone — what ZFM is, who uses it, the terms, how to get in touch. Public, at home.zebrafishfacilitymanager.com.
zf-usage	A facility's users — the usage guide and release notes. Ships inside every release; each facility serves its own at /usage-guide/.
zf-deployment-docs	Whoever stands a facility up. Public, at deployment.zebrafishfacilitymanager.com/production/.
zf-development-practices	Whoever works on the code. This site. Public, at deployment.zebrafishfacilitymanager.com/development/.
zf-data-migration	Whoever maps a new lab's existing records into a facility. Not published.

They are separate sites because the audiences are separate and are served differently — see deployment docs → Deploying the docs for where each one goes.

Tools

MkDocs is Python, so you need Python 3 and pip, plus the mkdocs-material theme that every site's mkdocs.yml selects.

Previewing while you write

From the directory holding a mkdocs.yml:

mkdocs serve                              # prints the URL it is serving on
mkdocs serve --dev-addr localhost:8001    # a second site at the same time

It watches for changes and recompiles on save, so the browser updates as you edit. mkdocs serve also reports a nav entry pointing at a file that does not exist, which is the usual way a site breaks.

mkdocs build writes a static site/ directory instead. That is a deployment step, not an authoring one, and site/ is gitignored — there is no reason to build one just to read a page locally.

What belongs here

A page is current or it is deleted. No "this used to work differently" notes and no stale procedure left in place for the record: git holds the history, and a reader cannot tell which half of a page still applies. The exception is a warning that stops someone taking a path which looks reasonable and is not — that is about the future, and it earns its space.

Documentation goes in the site that owns the topic. If a page already covers the subject, update that page rather than adding a second one beside it, and don't add a top-level .md at the repo root.