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

Clarity Checklist

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: ``bash 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:

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.

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.

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