| name | technical-writing-styleguide |
| description | Technical writing styleguide for clear, consistent documentation. Use when writing, editing, or reviewing technical content, guides, tutorials, or documentation. Triggers on article review, writing style, brand names, grammar check, screenshot guidelines, guide audit, technical docs. Use when this capability is needed. |
| metadata | {"author":"artivilla"} |
Technical Writing Styleguide
Quick Reference
Voice: first person plural ("we'll install..."), active voice, friendly and informal tone.
Point of view priority:
- First person plural to include the reader: "Next, we'll configure the server."
- Second person imperative for instructions: "Type
npm install."
Key rules:
- Be opinionated, not comprehensive — pick one approach and recommend it
- Never tell the reader something is "easy" or "obvious"
- Never start with personal background or definitions
- Avoid marketing speak and encyclopaedia-style content
- Use serial commas, common contractions, and sentence case for headings
- Place inline code between backticks, but use fenced code blocks for any runnable commands
- Put text before screenshots, never two screenshots in a row without text between them
Brand names: many tech brand names have irregular capitalization (JavaScript not Javascript, GitHub not Github, Node.js not NodeJS). Always verify against the brand-names reference.
Numbers: spell out numbers under ten and at the start of sentences. Use numerals for 10 and above. Numbers over three digits get commas (1,000).
Code blocks: always use fenced code blocks with language specifiers for code samples. Use backticks only for inline single-word references.
Principles
- Clear: keep words and sentences as simple as possible
- Useful: deliver on the promise your headline made
- Friendly: use informal language without patronizing the reader
Progressive Disclosure
- Full styleguide: see references/styleguide.md for voice, tone, structure, headings, code samples, and formatting conventions
- Grammar: see references/grammar.md for punctuation, capitalization, contractions, numbers, pronouns, and word list
- Brand names: see references/brand-names.md for correct capitalization of tech brand names
- Screenshots: see references/screenshots.md for resolution, annotations, gifs, and combining screenshots with text
- Guide audit: see references/guide-audit.md for pre-commit checklist when reviewing articles
Decision Guide
When reviewing or editing existing content
Load the grammar and styleguide references. Check brand names against the brand-names reference.
When writing a new tutorial or guide
Load the styleguide for structure and voice. Use the screenshots reference when adding visuals.
When doing a final review before publishing
Run through the guide-audit checklist to verify word count, structure, and content quality.
Source: artivilla/agents-config — distributed by TomeVault.
