Writing

Standards for writing and revising for the reader: voice, tone, structure, and formatting, and how to add new information to something that already exists. Each topic file covers a distinct concern.

Topics

• Optimize for the Reader: Fold new information in where it belongs, as if written once; supersede at the top once others have acted on it. Use when revising or adding to any existing document, issue, PR, instruction file, or code.

• Writing Style: Core writing standards — active voice, conciseness, parallel structure, sentence-case headings, and formatting rules. Use when writing or modifying prose.

• Clear Writing: Techniques for knowing what matters, building a hierarchy of points, and cutting noise. Use when writing or modifying prose.

• Dashes and Hyphens: Rules for hyphens, en dashes, and em dashes with keyboard shortcuts. Use when writing or modifying prose.

• What Before Why or How: Lead every document and section with the main idea before explaining context. Use when writing or modifying prose.

See also

• Code Style: Language-agnostic code formatting rules for indentation, line length, braces, and comments.