Features

Documentation Style Guide

Docs HomeHome
Status: active
DocsFeaturesDocumentation Style Guide

Documentation Style Guide

Status: active Last updated: 2026-04-15

Why This Exists

This guide keeps feature docs consistent, readable, and useful.

Without a shared style, docs become uneven. Some pages get too vague, some get too technical, and some stop matching the code.

Writing Principles

  • Use simple English
  • Prefer short sentences
  • Explain user value before implementation detail
  • Prefer concrete examples over abstract claims
  • Use stable headings so pages stay easy to scan
  • Be honest about gaps and unfinished areas

Default Page Structure

Use this structure for most feature pages:

# Feature Name

Status: active
Last updated: YYYY-MM-DD

## What It Is

Short plain-language summary.

## Why It Exists

What problem it solves for the product or user.

## Main Parts

- important folder or file
- important folder or file

## User Flow

1. What starts the flow
2. What the feature does
3. What the user sees

## Data And Rules

- important types
- key computed values
- important constraints

## Risks And Gaps

- known weakness
- known cleanup area

## Related Docs

- nearby feature docs

Naming Rules

  • Use README.md for a feature home or folder home
  • Use simple topic names like routing.md, history.md, editing-model.md
  • Avoid vague names like notes.md or misc.md

When To Add A Nested Page

Add a new nested page when:

  • a subfolder has its own mental model
  • one topic no longer fits cleanly in the main README.md
  • the feature has user-facing behavior that deserves its own explanation
  • the page would otherwise become long and hard to scan

File References

When a doc explains important implementation behavior, include the main files:

Language Rules For Layman Readability

  • Prefer what matters over criteria
  • Prefer better when the number is lower over minimize
  • Prefer saved version over snapshot when the context is user-facing
  • If a technical word must stay, explain it once near where it appears

Update Expectations

Update docs when:

  • a feature gains a new important flow
  • a data model changes meaningfully
  • a new subfolder becomes important
  • the UI language changes in a way the docs should match

Related Docs