Diff: reference/style-guide-guide

From d046f96 to d046f96

+0 / −0 lines
BeforeAfter
--- ---
schema: foundry-doc-v1 schema: foundry-doc-v1
title: "Style Guide — GUIDE" title: "Style Guide — GUIDE"
slug: style-guide-guide slug: style-guide-guide
category: reference category: reference
type: topic type: topic
quality: core quality: core
short_description: "How to write a GUIDE file: the operational runbook format used inside Foundry deployment subfolders, covering required structure, voice, command formatting, and the distinction from TOPIC files." short_description: "How to write a GUIDE file: the operational runbook format used inside Foundry deployment subfolders, covering required structure, voice, command formatting, and the distinction from TOPIC files."
status: active status: active
bcsc_class: public-disclosure-safe bcsc_class: public-disclosure-safe
last_edited: 2026-04-30 last_edited: 2026-04-30
editor: pointsav-engineering editor: pointsav-engineering
cites: [] cites: []
paired_with: style-guide-guide.es.md paired_with: style-guide-guide.es.md
--- ---
# Style Guide — GUIDE # Style Guide — GUIDE
> A GUIDE file is the operational runbook format for Foundry deployment subfolders — how to run, configure, or recover from failure — and is distinct from a TOPIC, which explains what something is and why. > A GUIDE file is the operational runbook format for Foundry deployment subfolders — how to run, configure, or recover from failure — and is distinct from a TOPIC, which explains what something is and why.
A **GUIDE** file (`guide-<subject>.md`) is an operational runbook — A **GUIDE** file (`guide-<subject>.md`) is an operational runbook —
how to run, configure, or recover from failure. It tells the how to run, configure, or recover from failure. It tells the
operator what to do, in order, with the commands they will copy operator what to do, in order, with the commands they will copy
and paste. It is not an explanation of why something works; that and paste. It is not an explanation of why something works; that
reasoning belongs in a TOPIC, covered in reasoning belongs in a TOPIC, covered in
[[style-guide-topic|Style Guide — TOPIC]]. Every GUIDE [[style-guide-topic|Style Guide — TOPIC]]. Every GUIDE
lives inside the deployment subfolder it operates; a GUIDE that lives inside the deployment subfolder it operates; a GUIDE that
appears at a catalog root without a containing subfolder is appears at a catalog root without a containing subfolder is
misplaced and must be moved. misplaced and must be moved.
## Where GUIDEs live ## Where GUIDEs live
GUIDEs live inside the deployment subfolder they operate. There GUIDEs live inside the deployment subfolder they operate. There
are two tiers: are two tiers:
| Tier | Path shape | Purpose | | Tier | Path shape | Purpose |
|---|---|---| |---|---|---|
| **Catalog** | `customer/woodfine-fleet-deployment/<deployment-name>/GUIDE-*.md` | Defines how this deployment-name is operated. Every catalog entry that is operationally meaningful carries at least one. | | **Catalog** | `customer/woodfine-fleet-deployment/<deployment-name>/GUIDE-*.md` | Defines how this deployment-name is operated. Every catalog entry that is operationally meaningful carries at least one. |
| **Instance** | `~/Foundry/deployments/<instance>/GUIDE-*.md` | Variation only when an instance has operationally significant deviations from its catalog GUIDE. | | **Instance** | `~/Foundry/deployments/<instance>/GUIDE-*.md` | Variation only when an instance has operationally significant deviations from its catalog GUIDE. |
A GUIDE at a fleet-deployment catalog *root* (no containing A GUIDE at a fleet-deployment catalog *root* (no containing
deployment subfolder) is misplaced. The workspace deployment subfolder) is misplaced. The workspace
`~/Foundry/CLAUDE.md` §14 names this as drift; move into the `~/Foundry/CLAUDE.md` §14 names this as drift; move into the
owning deployment subfolder. owning deployment subfolder.
## English only ## English only
GUIDE files are English-only. They are operational, not GUIDE files are English-only. They are operational, not
public-facing — bilingual pairs add maintenance cost without public-facing — bilingual pairs add maintenance cost without
benefit, because the audience is operators with English working benefit, because the audience is operators with English working
proficiency. This is the asymmetry against TOPIC files, which proficiency. This is the asymmetry against TOPIC files, which
are always bilingual. are always bilingual.
## Frontmatter is optional ## Frontmatter is optional
GUIDEs do not declare citations in the citation-substrate sense GUIDEs do not declare citations in the citation-substrate sense
because they describe procedures rather than make claims. A because they describe procedures rather than make claims. A
GUIDE may carry a brief frontmatter block declaring its GUIDE may carry a brief frontmatter block declaring its
deployment-name and last-verified date, but it is not required deployment-name and last-verified date, but it is not required
and the renderer does not depend on it. and the renderer does not depend on it.
```yaml ```yaml
--- ---
deployment: cluster-totebox-corporate deployment: cluster-totebox-corporate
last_verified: 2026-04-27 last_verified: 2026-04-27
--- ---
``` ```
The verification date is more meaningful than the edit date. A The verification date is more meaningful than the edit date. A
GUIDE that has not been re-verified against the live deployment GUIDE that has not been re-verified against the live deployment
in the last quarter is suspect; the date tells the operator in the last quarter is suspect; the date tells the operator
whether the procedure is fresh. whether the procedure is fresh.
## Required structure ## Required structure
Every GUIDE has four sections: Every GUIDE has four sections:
1. **Purpose** — one sentence saying what this GUIDE accomplishes. 1. **Purpose** — one sentence saying what this GUIDE accomplishes.
2. **Procedure** — numbered steps in imperative voice. 2. **Procedure** — numbered steps in imperative voice.
3. **Verification** — how the operator confirms each step worked. 3. **Verification** — how the operator confirms each step worked.
4. **Recovery** — what to do if a step fails. 4. **Recovery** — what to do if a step fails.
Sections that do not apply are not omitted. If the GUIDE Sections that do not apply are not omitted. If the GUIDE
describes a procedure with no recovery path (because the describes a procedure with no recovery path (because the
procedure is idempotent, for instance), the Recovery section procedure is idempotent, for instance), the Recovery section
says so explicitly. Omission would be ambiguous; a stated says so explicitly. Omission would be ambiguous; a stated
"no recovery needed; the operation is idempotent" is informative. "no recovery needed; the operation is idempotent" is informative.
## Voice — terse imperative ## Voice — terse imperative
GUIDEs use shorter sentences than TOPICs. Sentence-length GUIDEs use shorter sentences than TOPICs. Sentence-length
budget: mean around fourteen words, maximum around twenty-four. budget: mean around fourteen words, maximum around twenty-four.
Imperative voice — `run`, `confirm`, `restart`, `verify`. Active Imperative voice — `run`, `confirm`, `restart`, `verify`. Active
voice always; passive voice in a runbook hides who or what is voice always; passive voice in a runbook hides who or what is
doing the action, which matters when something fails. doing the action, which matters when something fails.
The banned-vocabulary list applies. The list includes verbal The banned-vocabulary list applies. The list includes verbal
tics that survive in operational prose (`leverage`, `seamless`, tics that survive in operational prose (`leverage`, `seamless`,
`robust`) — these have no place in a runbook because they `robust`) — these have no place in a runbook because they
describe nothing the operator can verify. describe nothing the operator can verify.
## Commands are copy-pasteable ## Commands are copy-pasteable
Every command in a GUIDE is in a fenced code block, alone on Every command in a GUIDE is in a fenced code block, alone on
its line, ready to copy and paste. Inline backtick code is for its line, ready to copy and paste. Inline backtick code is for
referring to a command, not running it. referring to a command, not running it.
```sh ```sh
systemctl status local-doorman.service systemctl status local-doorman.service
``` ```
Where a command takes arguments that the operator must Where a command takes arguments that the operator must
substitute, the placeholders are obvious — `<tenant-id>`, substitute, the placeholders are obvious — `<tenant-id>`,
`<instance-name>`, `<commit-sha>`. They are never `xxx`, `<instance-name>`, `<commit-sha>`. They are never `xxx`,
`YOUR_VALUE`, or `[insert here]`. `YOUR_VALUE`, or `[insert here]`.
## Verification is concrete ## Verification is concrete
Every step has a check the operator can run to confirm the step Every step has a check the operator can run to confirm the step
worked. The check is a command with an expected output, not a worked. The check is a command with an expected output, not a
narrative. "Verify the service is healthy" is not a check; narrative. "Verify the service is healthy" is not a check;
"`systemctl is-active local-doorman.service` returns `active`" "`systemctl is-active local-doorman.service` returns `active`"
is a check. is a check.
This rule applies to the procedure as a whole, not only to This rule applies to the procedure as a whole, not only to
individual steps. The Verification section at the bottom of the individual steps. The Verification section at the bottom of the
GUIDE confirms the post-condition the GUIDE is meant to GUIDE confirms the post-condition the GUIDE is meant to
establish. establish.
## Recovery is concrete ## Recovery is concrete
When a step fails, the operator should know exactly what to When a step fails, the operator should know exactly what to
try next. Recovery instructions name the failure mode they try next. Recovery instructions name the failure mode they
address, the diagnostic command that confirms the failure mode, address, the diagnostic command that confirms the failure mode,
and the corrective procedure. and the corrective procedure.
A GUIDE with vague recovery ("restart the service if it does A GUIDE with vague recovery ("restart the service if it does
not work") is worse than no GUIDE — it suggests the operator not work") is worse than no GUIDE — it suggests the operator
has options when in fact the procedure has not been thought has options when in fact the procedure has not been thought
through. Better to write "no automatic recovery; escalate to through. Better to write "no automatic recovery; escalate to
on-call" than to gesture at recovery without specifying it. on-call" than to gesture at recovery without specifying it.
## What a GUIDE is not ## What a GUIDE is not
A GUIDE is not a TOPIC. The reasoning, design intent, or A GUIDE is not a TOPIC. The reasoning, design intent, or
architectural background that motivates a procedure lives in a architectural background that motivates a procedure lives in a
TOPIC; the procedure itself lives in the GUIDE. A document that TOPIC; the procedure itself lives in the GUIDE. A document that
mixes both is split. mixes both is split.
A GUIDE is not a script. A script that the GUIDE invokes lives A GUIDE is not a script. A script that the GUIDE invokes lives
in the project's `scripts/` directory; the GUIDE references it in the project's `scripts/` directory; the GUIDE references it
by path. Embedding script logic in GUIDE prose duplicates by path. Embedding script logic in GUIDE prose duplicates
authority and rots when the script changes. authority and rots when the script changes.
A GUIDE is not a public-facing artefact. Operational detail — A GUIDE is not a public-facing artefact. Operational detail —
the SSH command shape, the systemd unit name, the on-call the SSH command shape, the systemd unit name, the on-call
escalation path — does not belong in TOPIC files served to a escalation path — does not belong in TOPIC files served to a
public audience. It belongs in GUIDEs read by operators with public audience. It belongs in GUIDEs read by operators with
deployment access. deployment access.
## See Also ## See Also
- [[style-guide-readme|Style Guide — README]] - [[style-guide-readme|Style Guide — README]]
- [[style-guide-topic|Style Guide — TOPIC]] - [[style-guide-topic|Style Guide — TOPIC]]
- [[language-protocol-substrate|Language Protocol Substrate]] - [[language-protocol-substrate|Language Protocol Substrate]]
- [[customer-hostability|Customer Hostability]] - [[customer-hostability|Customer Hostability]]
## References ## References
--- ---
*Copyright © 2026 Woodfine Capital Projects Inc. Licensed under [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/).* *Copyright © 2026 Woodfine Capital Projects Inc. Licensed under [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/).*
*Woodfine Capital Projects™, Woodfine Management Corp™, PointSav Digital Systems™, Totebox Orchestration™, and Totebox Archive™ are trademarks of Woodfine Capital Projects Inc., used in Canada, the United States, Latin America, and Europe. All other trademarks are the property of their respective owners.* *Woodfine Capital Projects™, Woodfine Management Corp™, PointSav Digital Systems™, Totebox Orchestration™, and Totebox Archive™ are trademarks of Woodfine Capital Projects Inc., used in Canada, the United States, Latin America, and Europe. All other trademarks are the property of their respective owners.*