Documentation Style Guide

Purpose: Canonical terminology and language patterns Authority: Use these terms consistently across all documentation Source: conductor/product-guidelines.md

Canonical Terminology

Infrastructure Terms

Use This	Not This	Context
`canonical endpoint`	primary endpoint, main endpoint	The authoritative URL for a service
`optional alias`	alternative, secondary	A convenience URL that points to canonical
`verified`	confirmed, checked	Proven by evidence
`assumed`	(avoid)	Use "unverified" instead
`manual verify`	check manually	Requires human verification via UI/dashboard
`verified via [method]`	tested with	Proven by specific tool/script

Service State Terms

Use This	Context
`Active`	Service is running and healthy
`Deleted`	Service was removed (include date)
`Deprecated`	Service exists but should not be used
`Planned`	Service does not exist yet (requires ADR)

Verification Status Terms

Tag	Meaning	When to Use
`VERIFIED`	Proven by evidence	Claim backed by code, script, or snapshot
`MANUAL VERIFY`	Requires human check	Cannot be scripted (UI-only setting)
`UNVERIFIED`	Not yet proven	Claim needs verification before trusting
`HISTORICAL`	Was true, may be stale	Archived content

Core Product Terminology

Always Capitalize

Term	Definition
Action	A governed tool execution with identity, inputs, outputs, policy decision, outcome
Policy	Defines what Actions are allowed, denied, or constrained
Decision	Evaluated result: Allowed / Denied / Constrained / Requires approval
Ledger	System of record for Actions: immutable records + provenance
Run	Structured sequence of Actions (replayable)

Modes

Term	Definition
Observe Mode	Record Actions without blocking
Enforce Mode	Apply Policy decisions and gates

Decision Outcomes

Use these exact terms for policy decisions: - Allowed - Denied - Allowed with constraints - Requires approval

Voice Patterns

Operator-Grade (Production/Security/Runbooks)

Characteristics: - Calm, precise, unambiguous - Deterministic language - Facts over reassurance

Signature Verbs:

Allowed | Denied | Constrained | Paused | Queued | Retried | Replayed | Exported

Example:

**BudgetExceeded**: Monthly Action budget reached.
New Actions are paused for `project:alpha`. Increase budget or wait until reset.

Developer-Legible (Tutorials/Guides/SDK)

Characteristics: - Clear, approachable, builder-oriented - Copy/paste commands - "Do this next" guidance

Signature Verbs:

Install | Configure | Verify | Integrate | Test | Deploy | Roll back

Example:

## Step 1: Install the SDK
```bash
pip install fulcrum-governance

Verify the installation:

python -c "import fulcrum; print(fulcrum.__version__)"

Expected output: 0.1.3

---

## Document Structure

### Required Opening

Every document must begin with:

```markdown
# [Title]
> **Purpose**: [What this document is]
> **Audience**: [Who should read it]
> **Verify**: [One command to validate it works]

Evidence Citation Format

<!-- Evidence: [source] -->
[Factual claim]

<!-- Evidence: docs/infra/PROD_TRUTH_MAP.md, verified 2026-01-31 -->
The MCP endpoint is `https://api.fulcrumlayer.io/mcp`.

<!-- UNVERIFIED: curl https://api.fulcrumlayer.io/health -->
Health check returns 200.

<!-- MANUAL VERIFY: Railway dashboard → fulcrum-server → Settings -->
Autodeploy is disabled.

Code Examples

Always include: 1. Copy/paste command 2. Expected output 3. Common failure (if applicable)

## Install

```bash
pip install fulcrum-governance

Expected output:

Successfully installed fulcrum-governance-0.1.3

Common failure:

ERROR: Could not find a version that satisfies the requirement

Solution: Ensure Python 3.9+ is installed.

---

## Words to Prefer

Use deterministic, precise language:

## Words to Avoid

| Avoid | Why | Use Instead |
|-------|-----|-------------|
| magic | Anthropomorphizes system | deterministic, automated |
| autopilot | Implies no control | policy-driven, constrained |
| AI thinks | Anthropomorphizes LLM | model evaluates, returns |
| safe AI | Unverifiable claim | governed, policy-enforced |
| oops, uh-oh | Unprofessional in production | Error: [code] |
| coming soon | Invented timeline | Planned (requires ADR) |
| we believe | Hedging | [factual statement] |

---

## Formatting Standards

### Headings
- Use sentence case: "Getting started" not "Getting Started"
- One H1 per document (the title)
- Logical hierarchy: H1 → H2 → H3

### Code Blocks
- Always specify language: ```bash, ```go, ```python
- Include expected output when relevant
- Use `inline code` for file paths, commands, variable names

### Tables
- Use for structured comparisons
- Include header row
- Align consistently

### Links
- Prefer relative paths within repo: `../runbooks/TRUTH_MAP.md`
- Use absolute URLs for external links
- Verify links exist before committing

---

## Error Message Format

[ErrorCode]: [Short description] {What happened} {Why} {What to do next}

Details: [request_id, action_id, etc.]

**Example:**
```markdown
**PolicyDenied**: Prod write requires approval.
Action `deploy_config` was denied by policy `prod-write-gate`.
Request approval from project admin or use staging environment.

Details: action_id=act_123, policy_id=pol_456

Style guide established: 2026-02-01 Source: conductor/product-guidelines.md