Style Guide Development

Create comprehensive style guides that ensure consistency, clarity, and quality across all technical documentation.

When to Use This Skill

• Establishing writing standards
• Ensuring consistency
• Onboarding writers
• Maintaining quality
• Defining terminology
• Setting voice and tone
• Creating templates
• Scaling documentation

Core Concepts

1. Style Guide Structure

# Technical Writing Style Guide

## Voice and Tone

- **Voice**: Professional, helpful, clear
- **Tone**: Friendly but not casual, respectful
- **Perspective**: Second person ("you"), active voice

## Writing Principles

1. **Clarity**: Use simple, direct language
2. **Conciseness**: Eliminate unnecessary words
3. **Consistency**: Follow established patterns
4. **Accuracy**: Verify all technical information

## Grammar and Mechanics

- Use sentence case for headings
- Oxford comma in lists
- Avoid exclamation marks
- Use contractions sparingly

## Terminology

| Prefer | Avoid |
|--------|-------|
| click | click on |
| sign in | log in, login |
| username | user name |
| email | e-mail |

## Code Examples

- Use syntax highlighting
- Include complete, runnable examples
- Add comments for clarity
- Show expected output

2. Voice and Tone Guidelines

## Voice and Tone Examples

### ✅ Good Examples

"To create a new project, click the + button in the dashboard."

"Your API key is located in Settings → API. Keep it secure."

"Error 404: The requested resource wasn't found. Check the URL and try again."

### ❌ Avoid

"Simply click the + button!" (too casual, unnecessary adverb)

"Your API key can be found..." (passive voice)

"Oops! Something went wrong!!!" (unprofessional)

Best Practices

1. Consistent standards – Clear rules for all scenarios
2. Living document – Update as needed
3. Example-driven – Show don’t tell
4. Team input – Collaborative development
5. Easy to find – Accessible location
6. Tool integration – Linters, spell checkers
7. Training materials – Onboarding resources
8. Version control – Track changes

Resources

• Google Developer Documentation Style Guide
• Microsoft Writing Style Guide
• Vale linter: Style guide enforcement