technical-writing
Write clear technical documentation following Google's style guide. Use when writing docs, README files, API documentation, code comments, user guides, or asking about documentation style.
When & Why to Use This Skill
This Claude skill automates the creation of high-quality technical documentation by strictly adhering to the Google Developer Documentation Style Guide. It ensures clarity, consistency, and professionalism across all technical assets—including READMEs, API references, and user guides—by prioritizing active voice, inclusive language, and developer-centric communication standards.
Use Cases
- Drafting and refining README.md files for software projects to ensure they meet professional industry standards for clarity and structure.
- Converting complex internal engineering notes into accessible user-facing documentation using a conversational yet professional tone.
- Auditing existing technical guides to remove jargon, filler phrases, and non-inclusive language while enforcing consistent capitalization and formatting.
- Writing structured API documentation and code comments that follow specific procedural guidelines and imperative verb usage for better developer experience.
- Standardizing documentation across a team by applying Google's style rules to ensure a unified voice and tone in all technical communications.
| name | technical-writing |
|---|---|
| description | Write clear technical documentation following Google's style guide. Use when writing docs, README files, API documentation, code comments, user guides, or asking about documentation style. |
Technical Writing
Write clear, consistent technical documentation based on Google's developer documentation style guide.
Core Principles
- Clarity over cleverness: Prioritize understandable prose over elegant writing
- Consistency matters: Apply rules uniformly throughout a document
- Audience-first: Write for developers with varying English proficiency
Voice and Tone
Use second person: Address the reader directly with "you."
Good: "You can configure the server by editing config.yaml."
Bad: "We can configure the server by editing config.yaml."
Use active voice: Make clear who performs the action.
Good: "The function returns an error code." Bad: "An error code is returned by the function."
Be conversational but professional: Write naturally without slang, jargon, or excessive formality. Use common contractions like "you're," "don't," and "it's" to maintain an informal tone.
What to Avoid
- Jargon and buzzwords: "leverage," "utilize," "synergy"
- Filler phrases: "please note that," "it should be noted"
- Exclamation marks: Reserve for genuinely exciting moments
- Implying simplicity: "simply," "just," "easy" (frustrates struggling readers)
- Latin abbreviations: Write "for example" not "e.g.", "that is" not "i.e."
- Directional language: Use "earlier/later" not "above/below"
- Anthropomorphic language: Don't attribute human qualities to software ("the system wants," "the server thinks")
- Skipping articles: Always include "a," "an," and "the"—even in headings
Inclusive Language
| Avoid | Use Instead |
|---|---|
| blacklist/whitelist | denylist/allowlist, blocklist/safelist |
| master/slave | primary/replica, leader/follower |
| man-hours | person-hours |
| guys | everyone, folks, team |
| sanity check | quick check, coherence check |
Capitalization
- Sentence case for headings: Capitalize only the first word and proper nouns
- Product names: Always capitalize (Tenzir, Kubernetes, Docker)
- Acronyms: Use standard capitalization (API, HTTP, JSON)
Headings
- Task headings: Use bare infinitives ("Create an instance")
- Concept headings: Use noun phrases ("User authentication")
- Hierarchy: Don't skip levels (h1 to h3 without h2)
- No links: Avoid hyperlinks within headings
Lists
Numbered lists: For sequential steps or ordered items.
Bulleted lists: For non-sequential items.
List guidelines:
- Introduce with a complete sentence followed by a colon
- Start each item with a capital letter
- Use parallel structure across items
- End with periods if items contain verbs or are complete sentences
- Don't use single-item lists
Procedures
Structure:
- Introduce with context
- Number each step
- Start steps with imperative verbs
- State location before action
Guidelines:
- "In the Settings panel, click Save." (location before action)
- Mark optional steps with "Optional:" at the start
- Document one accessible procedure, not multiple alternatives
- Avoid "please" in instructions
Code in Text
Use code font (backticks) for:
- Command-line input and output
- Filenames and paths
- Class, method, and function names
- Keywords, variables, and parameters
- HTTP status codes and methods
Don't use code font for:
- Product names and services
- URLs meant to be followed in a browser
- Domain names
Grammar: Don't inflect code elements. Write "send a POST request" not
"POST the data."
Word Choices
| Avoid | Use Instead |
|---|---|
| aka | also known as, or use parentheses |
| allows you to | lets you |
| config | configuration |
| admin | administrator |
| click on | click |
| check (checkbox) | select |
| uncheck | clear |
| higher/lower (versions) | later/earlier |
Formatting
- UI elements: Bold (File > Save)
- User input: Code font or bold, depending on context
- New terms: Italics on first use
- Emphasis: Use sparingly; prefer restructuring sentences
Links
- Use descriptive link text that makes sense out of context
- Avoid "click here" or "this page"
- Good: "See the authentication guide."
- Bad: "Click here for more information."
Reference Hierarchy
When style questions arise, consult in order:
- Project-specific guidelines
- Google Developer Documentation Style Guide
- Merriam-Webster (spelling)
- Chicago Manual of Style (general)
- Microsoft Writing Style Guide (technical)