Style Guide

This document defines the writing and formatting standards for the Engineering Knowledge Framework.

Purpose

This document defines the writing and formatting standards for the Engineering Knowledge Framework.

Consistency makes engineering knowledge easier to read, maintain, discover and evolve.

The style guide exists to ensure every document feels like it was written by a single author, regardless of how many contributors participate.

This document focuses on how knowledge should be written.

The philosophy behind the framework is documented in CLAUDE.md and Strategy.

AI-First Writing

The Engineering Knowledge Framework is designed to be consumed by both humans and AI systems.

Good engineering documentation naturally serves both audiences.

Documents should therefore maximize:

AI-friendly writing does not mean writing differently for humans.

Instead, it means writing with sufficient structure, explicitness and consistency that both humans and AI systems can accurately interpret the knowledge.

Writing Principles

Every document should strive to be:

Prefer clarity over cleverness.

Prefer simplicity over completeness.

Prefer principles over implementation details.

Front Matter

Every document begins with a YAML front matter block.

Front matter is what makes a document addressable by tooling. Without it, search can match only titles and file paths, the knowledge graph carries no summaries, and nothing can report which knowledge has gone stale.

---
title: "Service Objects"
description: "Service objects encapsulate a single business operation into a dedicated class."
type: guide
capability: rails
status: published
tags: [patterns, refactoring]
last_reviewed: 2026-07-28
---
FieldRequiredRule
titleYesThe document's display name. Prefer the curated title over the filename
descriptionYesOne sentence. Summarize the document, do not introduce a list
typeYesOne of the nine document types, plus adr, rfc, prompt, governance
capabilityYesThe owning capability
statusYesdraft, published or deprecated
tagsNoRetrieval hints beyond the words already in the title
last_reviewedYesYYYY-MM-DD. Update it when you genuinely review the content

Do not set last_reviewed to today's date for a mechanical edit. The field exists so that staleness can be reported honestly.

File Naming

ConventionExampleRule
Lowercasehandbooks/rails/README.mdNo capital letters in filenames or directory names
Hyphen-separatedservice-objects.mdUse hyphens, never spaces or underscores
Markdown extensiontesting-strategies.mdAll documents use .md extension
Directory indexhandbooks/engineering/README.mdEach directory has a README.md as its index

Choose descriptive names.

Avoid abbreviations unless they are universally understood.

Document Structure

Documents should follow a logical progression.

General guidance:

  1. Purpose
  2. Background
  3. Principles
  4. Main Content
  5. Examples
  6. References

Specific document structures are defined in Document Types.

Single Responsibility

Every document should answer one primary question.

Examples:

QuestionDocument Type
Why?Handbook
How does it work?Guide
How do I perform it?Playbook
Did I finish everything?Checklist
Where do I start?Template
What does this mean?Glossary
What should I learn next?Learning Path

If a document attempts to answer several unrelated questions, split it into multiple documents.

Smaller documents are easier to maintain and significantly improve AI retrieval.

Headings

Use descriptive headings.

Avoid vague titles.

Good:

Avoid:

A heading should remain meaningful when viewed independently in search results or a table of contents.

Do not skip heading levels. For example, do not jump from ## to #### without ### in between.

Prefer three heading levels or fewer whenever practical.

Voice and Tone

Write for experienced engineers.

Assume competence.

Use:

Avoid:

Good:

Controllers should remain thin.

Avoid:

Controllers might perhaps benefit from being relatively small.

Semantic Writing

Write so that each paragraph remains understandable in isolation.

Avoid ambiguous references.

Good:

The Rails application loads configuration during initialization.

Avoid:

It loads configuration.

Prefer explicit nouns over pronouns when ambiguity is possible.

State assumptions explicitly.

Do not rely on surrounding context.

Context Independence

Engineering documents are often consumed through search or AI retrieval.

Readers may encounter only part of a document.

Whenever practical:

Good:

See the Rails Engineering Handbook for architectural principles.

Timeless Writing

Prefer knowledge that remains valuable over implementation details that change frequently.

Good:

Avoid:

Version-specific information belongs in references rather than handbooks.

Explain:

These age far more gracefully than implementation details.

Canonical Sources

Every engineering concept should have a single authoritative source.

Other documents should reference that source rather than duplicate it.

Examples:

Duplication increases maintenance effort and causes knowledge to drift.

Links

Prefer explicit links.

Every significant concept should be connected to related knowledge.

Good:

[Code Review Playbook](./playbooks/code-review/)

Avoid:

See the code review documentation.

Knowledge Graph

The repository should evolve into a connected knowledge graph rather than a collection of isolated documents.

Documents should both:

Example:

Rails Handbook → Service Objects Guide → Code Review Playbook

Navigation should emphasize relationships rather than directory structure.

Lists

Use unordered lists (-) for collections.

Use ordered lists (1.) for sequences.

Keep nesting shallow.

Avoid deeply nested lists.

Bullet Format

Use - for bullet list items, never *.

Markdown accepts -, * and + interchangeably. The framework standardizes on - so that documents are diffable, greppable and consistent for both readers and tooling.

Correct:

- Item one.
- Item two.
  - Nested sub-item.

Incorrect:

* Item one.
+ Item two.

The examples are shown inside code fences deliberately. Written as live Markdown, every variant renders identically, which is what makes the inconsistency easy to introduce and hard to notice.

Checklist Format

Use - [ ] for checklist items.

Correct:

Tables

Use markdown tables for structured information.

Tables are appropriate for:

Avoid using tables for layout.

Format

Every table must follow this structure:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |

Rules:

  1. The first row is the header.
  2. The second row is the separator: |---|---| (pipes with dashes).
    • Always use | between columns in the separator row, never +.
    • Each column separator has three or more dashes: |---|.
  3. Data rows follow, one per row.
  4. All rows must have the same number of columns.
  5. A blank line ends the table.

Correct Example

| Principle      | Description                        |
|----------------|------------------------------------|
| Keep it simple | Prefer simple over clever designs. |
| Single purpose | One responsibility per module.     |

Rendered:

PrincipleDescription
Keep it simplePrefer simple over clever designs.
Single purposeOne responsibility per module.

Common Mistakes

Mistake 1: Using + in the separator row (org-mode style)

This is the most common and destructive error. The separator row must use | between columns, never +. Using + creates invalid markdown and renders incorrectly.

# Wrong — do NOT use + in separators:
| Pro | Con |
|-------+-------|    ← WRONG: + between columns
| Domain is testable | Increased complexity |

# Correct:
| Pro | Con |
|-----|------|
| Domain is testable | Increased complexity |

Mistake 2: Extra separator rows mid-table

Only one separator row is needed (between header and data). Do not add extra |---|---| rows in the middle of the table.

# Wrong — extra separator in data:
| Type | Description |
|------|-------------|
| Unit | Fast tests. |
|------|-------------|    ← WRONG: redundant separator
| E2E  | Slow tests. |

# Correct:
| Type | Description |
|------|-------------|
| Unit | Fast tests. |
| E2E  | Slow tests. |

Mistake 3: Inconsistent column count

Every row must have the same number of |-separated cells.

# Wrong — first row has 2 columns, second has 3:
| Name | Role |
|------|------|
| Alice | Engineer | Lead |    ← WRONG: 3 cells instead of 2

# Correct:
| Name | Role |
|------|--------|
| Alice | Engineer |

Multi-line Cells

Standard markdown does not support multi-line cells natively. For content that needs multiple lines (common in glossaries), use continuation rows with an empty first cell:

| Property | Value                                                |
|----------|------------------------------------------------------|
| Definition | A short document that captures an architectural     |
|           | decision, its context and alternatives.              |
| Context  | ADRs provide a historical record of why the          |
|           | system is the way it is.                             |

Rendered:

PropertyValue
DefinitionA short document that captures an architectural decision, its context and alternatives.
ContextADRs provide a historical record of why the system is the way it is.

Continuation rows must have the same number of | characters as the header (even if some cells are visually empty).

Or use a list within a cell if the renderer supports it (most do not). For complex multi-line content, prefer a definition list or bullet list outside the table.

Blockquotes

Use > for blockquotes.

Used for:

Example:

Controllers should remain thin. Move business logic into service objects or models.

Code Blocks

Always specify the language for syntax highlighting.

Example:

class User < ApplicationRecord
  has_many :posts
end

Prefer small examples.

Examples should demonstrate principles rather than complete applications.

Examples

Examples should be:

When appropriate, include:

Examples are often the fastest way to teach engineering concepts.

Cross References

Prefer links over repeated explanations.

If knowledge already exists elsewhere, reference it.

Every document should contribute to the repository's knowledge graph.

Terminology

Use terminology consistently.

Define new terminology in the appropriate glossary.

Avoid introducing multiple names for the same concept.

Prefer:

Avoid unnecessary synonyms.

AI Readability

Documents should optimize retrieval quality.

Prefer:

Avoid:

Good documentation naturally improves AI performance.

Continuous Evolution

Engineering knowledge evolves.

Improve existing documents before creating new ones whenever practical.

Documentation refactoring is encouraged.

Repository quality is more important than document count.

Validation Checklist

Run make validate before committing. It enforces every item marked automated below and fails the build on any violation.

The remaining items require human judgement and are not enforceable by tooling.

Automated:

Requires review:

AI Readability Checklist

Additionally verify:

References