technical-writing-style

Technical Writing Style Guide

Style and voice guidelines for creating clear, engaging technical blog content.

Overview

This skill provides standards for technical blog writing that balances accessibility with technical depth. It covers voice, tone, sentence structure, and language choices that make technical content engaging and easy to follow.

This skill covers:

• Voice and tone standards for technical content
• Sentence structure and clarity guidelines
• Terminology consistency practices
• Reader engagement techniques

This skill does NOT cover:

• Content structure and organization (see content-structure-patterns)
• Code example formatting (see code-example-best-practices)
• SEO optimization

Quick Reference

Voice Guidelines

Principle	Do	Don't
Active voice	"Run the command"	"The command should be run"
Direct address	"You can configure..."	"One can configure..."
Present tense	"This function returns..."	"This function will return..."
Confident tone	"Use X for Y"	"You might want to use X"

Clarity Checklist

Check	Target
Sentence length	Under 25 words
Paragraph length	3-4 sentences
Jargon ratio	Define or avoid 80%+
Passive voice	Less than 10%

Principles

1. Write for Scanners First

Technical readers scan before reading. Support this:

• Use descriptive headings that convey meaning
• Lead paragraphs with the key point
• Use bullet points for lists of 3+ items
• Bold key terms on first introduction

2. One Idea Per Paragraph

Each paragraph should:

• Start with a topic sentence
• Support that single idea
• Transition smoothly to the next

Example:

Caching reduces database load by storing frequently accessed data in memory. When a request arrives, the cache checks for existing data before querying the database. This simple pattern can reduce response times by 90% for read-heavy workloads.

3. Explain, Then Show

Follow this pattern:

1. State what something does
2. Explain why it matters
3. Show how to use it

Example:

Environment variables separate configuration from code. This lets you deploy the same application to different environments without code changes. Set them in your shell:

export DATABASE_URL="postgres://..."

4. Respect Reader Time

• Get to the point quickly
• Cut filler words ("basically", "actually", "just")
• Remove redundant phrases ("in order to" → "to")
• Use concrete words over abstract ones

Tone Guidelines

Technical but Accessible

Write as a knowledgeable peer, not a textbook:

Textbook	Peer
"It is necessary to initialize the configuration prior to execution"	"Initialize the config before running"
"The aforementioned methodology"	"This approach"
"Utilize"	"Use"

Confident but Humble

• Be direct about what works
• Acknowledge trade-offs and alternatives
• Admit when something is complex
• Avoid oversimplifying difficult concepts

Engaging but Professional

• Use "you" to address the reader
• Vary sentence structure
• Include occasional personality, but prioritize clarity
• Avoid jokes that might confuse non-native speakers

Common Issues

Hedging Language

Problem: Excessive hedging weakens authority.

Weak	Strong
"You might want to consider using..."	"Use..."
"It's probably a good idea to..."	"..." (just state it)
"This could potentially cause..."	"This causes..."

When hedging IS appropriate:

• Genuinely uncertain outcomes
• Multiple valid approaches
• Environment-specific behavior

Jargon Without Context

Problem: Assumes knowledge readers may not have.

Solution: Define on first use or link to explanation:

GraphQL uses resolvers—functions that fetch the data for each field in your schema.

Passive Voice Overuse

Problem: Obscures who does what.

Passive	Active
"The error is thrown when..."	"The function throws an error when..."
"Configuration must be provided"	"You must provide configuration"
"The file is read by the parser"	"The parser reads the file"

Formatting Standards

Headings

• Use sentence case: "Setting up authentication"
• Be specific: "Configuring Redis" > "Configuration"
• Limit nesting to 3 levels (H2, H3, H4)

Lists

• Use bullets for unordered items
• Use numbers for sequences or rankings
• Start each item with the same part of speech
• Keep items parallel in structure

Emphasis

• Bold for key terms on first introduction
• code for commands, functions, file names
• Italics sparingly, for emphasis or titles
• Never use ALL CAPS for emphasis

See Also

• content-structure-patterns skill - Blog organization patterns
• code-example-best-practices skill - Code snippet guidelines
• seo-specialist agent - SEO optimization