Skip to content

Write the operator guide #42

Description

@iderex

The release only means something if somebody who has never seen this board can use
it in a few minutes. Write the page that makes that true.

The shape it has to have. Download one file. Verify its checksum, with the command
written out for each platform, because a checksum nobody knows how to check is
decoration. Run one verb. Read what it printed.

What the operator gets, said in one paragraph near the top so they can decide
whether to continue. The runner reads a checkout of this board and tells them
whether its records are in order and what it examined. It changes nothing, it sends
nothing anywhere, and it needs no privileges. Somebody deciding in thirty seconds
whether to run an unfamiliar binary is asking exactly those three questions.

Include the failure paths, because they are what people actually hit. What a
refusal looks like and how to read it. What the exit codes mean. What a run over a
tree with no experiments prints, since that is what the first run produces and a
reader needs to know it is a real result rather than a broken one.

The page names the notice, the licence and the privacy document, and says the same
thing about personal data staying on the host that the privacy document says. Saying
it in both places is deliberate here, because the operator guide is the only one of
the two that a downloader is certain to open.

Done when docs/operator-guide.md exists on the default branch, walks download,
checksum and first run, quotes the exact output of a first run against a fresh
clone, and explains every exit code the runner can return.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions