writing-docs

Writing documentation

Overview

This skill covers the structure of documentation: what a page is for, how it is organized, and how its parts are formatted. The voice and word choice rules already apply to everything you write; this skill adds the structural conventions of the Google developer documentation style guide, condensed and adapted for code repositories.

When to use

Use it when you create or change a documentation file (Markdown, RST, AsciiDoc, HTML), a README, a design document or ADR, a changelog entry, a docstring, or a comment block that explains a module, type, or function.

Do not use it for commit messages, pull request descriptions, chat replies, or inline comments of a line or two. Those follow the writing style on their own. Do not use it for the code itself; formatting of docstrings and comments follows the language's conventions, and this skill governs only the prose inside them.

Before you write

Name the reader and pick one purpose for the page: explain a concept, complete a task, look something up, or learn by doing. A page that mixes purposes is harder to use than two short pages. Be prescriptive: recommend one path and mention alternatives only when the reader needs them to decide.

Core rules

Headings: sentence case; task headings are bare infinitives ("Create an instance"), concept headings are noun phrases ("Instance lifecycle"); no -ing openers, no numbering, no code, no links, no trailing punctuation; one H1 per page; never skip a level; never leave a heading without content.

Paragraphs: one idea each, one to four sentences, key point first. Break long paragraphs rather than lengthening sentences.

Lists: introduce a list with a complete sentence ending in a colon; use a numbered list only for a sequence; use a bulleted list for three or more parallel items; capitalize each item; end items that are sentences with a period; use term-and-description pairs with colons, never dashes; never make a list of one item.

Procedures: one action per step; state the goal or location before the action ("In the Settings page, select Billing"); prefix optional steps with "Optional:"; write a single-step procedure as one bullet; put results after the action, in the same step.