artivilla/technical-writing-styleguide

Technical Writing Styleguide

Quick Reference

Voice: first person plural ("we'll install..."), active voice, friendly and informal tone.

Point of view priority:

1. First person plural to include the reader: "Next, we'll configure the server."
2. 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.