SCHEMABOUND Documentation — Editorial Style Guide

Consistency rules for terminology, formatting, and tone across all documentation assets. These guidelines ensure that readers encounter uniform language regardless of which page they’re reading, reducing cognitive friction when switching between conceptual explanations, how-to guides, and reference material.

Nomenclature Consistency

SCHEMABOUND has a specific set of canonical terms that must be used exactly as written. Deviating from these terms creates confusion for readers trying to look up information elsewhere in the documentation or in code comments.

* Use “OAM” only when referring to the paradigm itself; always introduce as “Object Agent Mapping (OAM)” on first use in any document.

Terminology Definitions

These terms appear frequently across SCHEMABOUND documentation and must be defined at first usage:

Formatting Rules

Tables

Use Markdown tables for configurations, environment variables, and OCSF class mappings — never bullet lists when presenting quantitative reference material. Tables make it easier for operators to scan and compare values during incident response or capacity planning.

| Variable | Default | Purpose |
|---|---|---|
| `SCHEMABOUND_AUDIT_STDOUT` | `ocsf` | Stderr output format: `ocsf`, `json`, or `off` |

Code Blocks

Always include a language identifier for syntax highlighting:

# Correct
```rust
let executor = GrpcExecutor::new(..);

Incorrect

let executor = GrpcExecutor::new(..);

Supported languages: `rust`, `python`, `typescript`, `go`, `bash` (for shell commands), `json` (for API payloads), `mermaid` (for architecture diagrams).

### API Endpoints

Use HTTP method + path format for all endpoint references. Always include the leading slash and quote the full path:

```markdown
# Correct
- `GET /billing/usage` returns daily AAU totals
- POST to `/api/plans/:plan_id/steps` creates a new step

# Incorrect
- GET billing usage returns...
- api.plans.plan_id.steps

Error Types

Format Rust enum variants using backtick formatting with the module path prefix:

# Correct
The executor returns `ExecutorError::ConnectionFailed` when the target database is unreachable.

# Incorrect
"connection failed error", "Executor Error: Connection Failed", ExecutorError::Connection_Failed

Callout Boxes (Summary Cards)

Use mdbook’s blockquote syntax for TL;DR summary cards at the top of complex pages. Always include both a one-paragraph overview and a “use this page if you need to…” section that helps readers decide whether to continue reading:

> **TL;DR** — [one-sentence overview of what this page covers]
> 
> **Use this page if you need to:** [3-5 bullet points describing reader goals this page addresses]

## Key Configuration (optional, for operational pages)

| Variable | Default | Purpose |
|---|---|---|

Tone and Voice

Do

• Be precise, technical, and concise. Assume the reader is a competent engineer who is unfamiliar with SCHEMABOUND specifics but understands general software architecture concepts.
• Use active voice: “SCHEMABOUND validates tokens against…” rather than “Tokens are validated by SCHEMABOUND…”
• Provide exact values when possible: “RESTART_BASE_DELAY_SECONDS defaults to 5” rather than “the delay is configurable.”

Don’t

• Use marketing language (“revolutionary”, “game-changing”, “best-in-class”). Technical documentation should inform, not persuade.
• Explain basic programming concepts (Rust lifetimes, Python decorators, TypeScript generics) — readers of this documentation are expected to know their primary language.
• Use ambiguous pronouns: “This feature allows you to…” should specify what “this feature” is.

Cross-Referencing

Use relative links within the documentation so that all references work whether viewed locally via mdbook serve or deployed to a static site. Never use absolute URLs unless linking to external resources (GitHub repositories, official spec documents).

# Correct — Relative links within docs
See [Control Plane Reference](../reference/control-plane-reference.md) for gRPC definitions.

# Incorrect — Absolute or broken paths
See https://github.com/schemabound/... 
See ../../docs/reference/control-plane.md (fragile to restructure)

External references are reserved for:

• GitHub repositories (https://github.com/schemabound/)
• Official specification documents (OIDC spec, OCSF schema registry)
• Third-party documentation (mdbook, Docusaurus, Mermaid) that readers may need for troubleshooting build issues

Review Checklist

Before submitting any PR that modifies SCHEMABOUND documentation, verify:

• All new terms follow the canonical nomenclature table above
• Code blocks include language identifiers
• API endpoints use METHOD /path format with leading slash
• Error types are formatted as `Module::EnumVariant`
• Tables used for configurations instead of bullet lists when presenting quantitative data
• Cross-references use relative links within the documentation tree
• Summary cards include both TL;DR paragraph and “use this page if you need to” section on complex pages