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.
1---2name: technical-writing-styleguide3description: 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.4---56# Technical Writing Styleguide78## Quick Reference910**Voice**: first person plural ("we'll install..."), active voice, friendly and informal tone.1112**Point of view priority**:131. First person plural to include the reader: "Next, we'll configure the server."142. Second person imperative for instructions: "Type `npm install`."1516**Key rules**:17- Be opinionated, not comprehensive — pick one approach and recommend it18- Never tell the reader something is "easy" or "obvious"19- Never start with personal background or definitions20- Avoid marketing speak and encyclopaedia-style content21- Use serial commas, common contractions, and sentence case for headings22- Place inline code between backticks, but use fenced code blocks for any runnable commands23- Put text before screenshots, never two screenshots in a row without text between them2425**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.2627**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).2829**Code blocks**: always use fenced code blocks with language specifiers for code samples. Use backticks only for inline single-word references.3031## Principles3233- **Clear**: keep words and sentences as simple as possible34- **Useful**: deliver on the promise your headline made35- **Friendly**: use informal language without patronizing the reader3637## Progressive Disclosure3839- **Full styleguide**: see [references/styleguide.md](references/styleguide.md) for voice, tone, structure, headings, code samples, and formatting conventions40- **Grammar**: see [references/grammar.md](references/grammar.md) for punctuation, capitalization, contractions, numbers, pronouns, and word list41- **Brand names**: see [references/brand-names.md](references/brand-names.md) for correct capitalization of tech brand names42- **Screenshots**: see [references/screenshots.md](references/screenshots.md) for resolution, annotations, gifs, and combining screenshots with text43- **Guide audit**: see [references/guide-audit.md](references/guide-audit.md) for pre-commit checklist when reviewing articles4445## Decision Guide4647### When reviewing or editing existing content48Load the **grammar** and **styleguide** references. Check brand names against the **brand-names** reference.4950### When writing a new tutorial or guide51Load the **styleguide** for structure and voice. Use the **screenshots** reference when adding visuals.5253### When doing a final review before publishing54Run through the **guide-audit** checklist to verify word count, structure, and content quality.5556---57> Source: [artivilla/agents-config](https://github.com/artivilla/agents-config) — distributed by [TomeVault](https://tomevault.io).58<!-- tomevault:4.0:skill_md:2026-06-09 -->
tomevault-io