Writing the Admin Guide (operator docs)

Audience: whoever writes the operator-facing Admin Guide · Scope: how to write and organise admin-guide/ — the day-to-day administration area · Last reviewed: 2026-07-20

Part of the documentation standards; builds on writing.md, and is the operator-facing counterpart to features.md.

TL;DR — The Admin Guide (admin-guide/) is a separate documentation area for the people who run Beta-Calco day to day — data entry, settings, imports, reading the sheets. Its articles are plain-language, task-oriented how-tos and self-train walkthroughs, with no code, file paths, class names, SQL, or architecture — nothing that would overwhelm a non-developer. It is grouped by System (mirroring the reference docs) so an admin can self-train on a feature or look up a forgotten task, and it is a separate Docusaurus section so admins never see the developer docs.

Living standard — amend it.

---

Who it's for — and what it is not

• For: operators / admins doing data entry, changing settings, running imports, turning things on/off, and reading the exported sheets. They know the product, not the code.
• Not for: developers or AI agents — that's the reference docs in docs/.
• The litmus test: if a sentence needs a file path, class name, DB column, SQL, migration number, or "the controller/model/cron script," it belongs in the reference docs, not here. An Admin Guide article talks about screens, buttons, fields, and outcomes — what the admin sees and does.

Where it lives

• A top-level admin-guide/ folder, separate from docs/. In Docusaurus it is its own docs instance with its own sidebar and a navbar item ("Admin Guide"), so an admin lands in a world with none of the developer docs. (Config to add when the site is scaffolded: a second @docusaurus/plugin-content-docs instance rooted at admin-guide/, routeBasePath: '/admin', plus the navbar link.)
• Structure mirrors the reference docs — grouped by System, so the two stay recognisably parallel:

admin-guide/
  README.md                     ← "Start here": what this area is + the list of systems
  quote-follow-up/
    _category_.json             ← sidebar label + order
    README.md                   ← the system's task list (landing)
    nudge-cadence.md            ← one task = one article
    import-pipedrive-stages.md
    tracking-sheets.md

Article titles are tasks, not features — "Change how often a quote reminds you", not "Nudge cadence". The System grouping gives structure; the article names speak the admin's language.

The two article types

• Walkthrough — self-train on a feature end to end. Use when a new feature ships and an admin needs to learn the whole flow once.
• How-to — one task, look it up. Use for the recurring "how do I change X again?" moments.

Keep each article to one job. Split a sprawling one.

The shape of an article

# <Do the task, in the admin's words>

> **Audience:** operators · **Scope:** <the one task> · **Last reviewed:** YYYY-MM-DD

**What this does** — the outcome in one or two plain sentences (why you'd do it).

## Before you start        ← access / where to be / what to decide
## Steps                   ← numbered, UI-anchored: "Go to Settings → … → open the stage → …"
## What happens next       ← the effect, in plain terms (e.g. "on the next scheduled run …")
## Good to know            ← the things people forget: blank = off, preserved on re-import, not instant, …
## Troubleshooting         ← optional: "if you don't see X…"

Writing rules

• Second person, plain language, short steps. "You", "click", "enter". No jargon; define an unavoidable term in one line.
• Name the exact on-screen labels ("Settings → Quote Follow-ups → Imported Pipedrive Stages"), and what the admin will see and type.
• Screenshots are welcome — co-locate the image next to the article and reference it relatively.
• No developer internals — see the litmus test above.
• Link only to other Admin Guide articles. The single bridge to the reference docs is an optional "For developers →" line at the very bottom; the body never sends an admin into docs/.
• That bridge is a plain path, not a link — write For developers → `docs/pipedrive/README.md`. The Admin Guide and the reference docs are two separate Docusaurus instances, so a relative .md link between them cannot be resolved and fails the build under onBrokenLinks: throw. A backticked path works everywhere: the site, GitHub, and an AI reading the file raw. The same applies in reverse, in docs/.
• Hedge UI drift — labels can differ by environment; add a one-line "if a label doesn't match, check with your Beta-Calco contact."

Relationship to the reference docs' "Admin settings" section

They are parallel, not duplicate: a feature's reference doc has a mandatory Admin settings table (the technical reference — setting name, where stored, default) for developers/AI; the Admin Guide has the operator how-to for the same settings, in plain language. Same feature, different audience and depth — that overlap is intentional. When a feature ships that operators touch, "done" includes both the reference doc's Admin settings section and an Admin Guide article (that's what lets admins self-train on it).

Docusaurus notes

Everything in writing.md → Docusaurus-friendly conventions applies here too: kebab-case filenames, folder = category with a README.md index + _category_.json, wrap <placeholders>/{braces} in code, description front matter, relative .md links. The one addition is the separate docs instance above, so the Admin Guide is its own navbar section.

Checklist — an Admin Guide article is done when…

• The title is a task in the admin's words.
• No code, paths, class names, SQL, migrations, or architecture — only screens, fields, and outcomes.
• Steps name the exact menu path and on-screen labels; it says what the admin will see and enter.
• "What this does" / "What happens next" explain the effect in plain terms.
• "Good to know" captures the things admins forget (off switches, re-import behaviour, timing).
• Filed under the right System folder; the system README.md links to it.
• Links point to other Admin Guide articles (one optional "For developers →" bridge at the bottom).