Editorial Style Guide

Use this style guide to keep blue book content consistent as new pages, examples, and templates are added.

Voice

Write for consultants and client platform teams who need to make decisions quickly. Prefer direct, practical guidance over abstract explanation.

Good blue book writing is:

• Specific about when guidance applies.
• Clear about the recommended default.
• Honest about tradeoffs and watchouts.
• Focused on ownership, evidence, and action.
• Safe for client-facing reuse.

Page pattern

Most pages should follow this shape:

1. Short purpose statement.
2. When or why to use the guidance.
3. Practical checklist, workflow, or decision points.
4. Expected outputs or evidence.
5. Watchouts or failure modes.
6. Links to related pages when useful.

Language rules

• Use "should" for recommended defaults.
• Use "must" only for hard requirements.
• Avoid vendor hype and unverifiable claims.
• Avoid client-specific names, screenshots, or sensitive details.
• Use synthetic examples for services, users, systems, and data.
• Define new terms in the Glossary when they become reusable.

Diagrams

Use diagrams when they clarify flow, ownership, or dependency. Avoid large diagrams that try to explain an entire operating model at once. If a diagram is hard to read in the docs layout, split it or replace it with a table.

Tables and checklists

Use tables for comparison and checklists for action. Keep table cells short enough to scan. If a table needs paragraphs, it probably wants subsections instead.

Watchouts

• Do not add pages just to increase coverage.
• Do not duplicate guidance when a link would work.
• Do not bury decisions in long prose.
• Do not let examples imply a real client system or person.