Terminal
Terminal/Skill
Applies Google developer documentation style rules to any prose you write, including docs, error messages, commit messages and PR descriptions.
By InfluxData
Works with
npx skills add influxdata/docs-skills --skill gdd-styleApply this style to any prose you write for a person to read. Your chat replies count, not only files. Documentation, commit messages, PR bodies, and code comments all follow the same rules.
Write clearly and directly, never stiff and never cute. Readers often need every technical detail to be exact, are in a hurry, read English as a second language, or use a screen reader. Every rule below serves one of those four readers.
filenames, flags, env_vars, function(), literal values.
Tag fenced code blocks with a language.| Instead of | Write |
|---|---|
| please, simply, just, easy, obviously, of course | (delete it: it adds nothing or blames a struggling reader) |
| e.g., i.e., etc., via | for example, that is, and so on, through |
| may (ambiguous) | can (ability) or might (possibility) |
| leverage, utilize, enable you to | use, let you |
| sanity check, dummy value, crazy, blind to | check, placeholder, surprising, unaware of |
| kill, hang, abort, blacklist/whitelist, master/slave | stop, stop responding, cancel, blocklist/allowlist, primary/replica |
| man-hours, mankind | person-hours, humanity |
| hover over, hit | point to, press |
Also avoid exclamation points, pop-culture references, idioms that don't translate, "let's do X" phrasing, and starting every sentence with "You can."
No rhetorical framing. Don't open with a question, a hook, or a claim about how important something is. Cut "Ever wondered how caching can transform your app's performance?" Keep "Caching reduces repeated database reads." Drop marketing adjectives with it: seamless, powerful, robust, cutting-edge.
Precision, not decoration. Use the exact term the reader needs, such as mutex, idempotent, or backpressure, instead of a vaguer paraphrase. The term must be standard in the domain. Define a term the first time a less experienced reader depends on it. Qualifiers that bound a claim are precision too: only, up to, at most, exactly, never, by construction. Keep them.
Metaphors follow the literal statement. A metaphor can build intuition after a precise technical statement. It never replaces the statement.
| Not recommended | Recommended |
|---|---|
| Please note that the config file may be located in your home directory. | The config file might be in your home directory. |
| Simply run the migration script and you're golden! | Run the migration script. |
| We've now Added Support For Retries. | You can now retry failed requests. |
| Click here for more info. | See Configure retries. |
These rules govern prose.
Code samples, command syntax, literal API signatures, and program output are exempt.
The word swaps don't apply to them either:
kill -9 and a branch named master stay as they are.
Reread the draft once and ask:
Output the revised content, not a description of what you changed, unless the user asked for a diff or an explanation.
Clarity beats tone. If you can't make a sentence sound conversational, make it unmistakable instead.
Fidelity beats style. It serves the reader who needs every detail exact. Every rule above yields to what the source says. If a sentence can't follow a rule without changing its meaning, leave it as written.
Before you finish a revision, run a fidelity check:
The revision is done when every paragraph passes step 2.