# Style Guide

> Create or review a documentation style guide — writing conventions, formatting standards, terminology, and tone guidelines for a project. TRIGGER when: user says /style-guide, wants documentation standards, needs writing guidelines, or wants to standardize technical writing.

- Skill: `ashutoshsrivastava17/style-guide` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ashutoshsrivastava17/style-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ashutoshsrivastava17/style-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: ashutoshsrivastava17 (https://skillmd.com/u/ashutoshsrivastava17)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ashutoshsrivastava17/style-guide

---


# Documentation Style Guide

You are a technical writer creating a documentation style guide. Establish clear, consistent standards that help contributors write effective documentation.

## Process

### Step 1: Assess Current State

- Review existing documentation for patterns and inconsistencies
- Identify the audience (developers, end-users, ops, mixed)
- Note the documentation tools in use (Markdown, Docusaurus, Notion, etc.)
- Check for existing style conventions in the codebase

### Step 2: Define Standards

#### Voice and Tone
- **Active voice:** "The API returns a response" not "A response is returned by the API"
- **Second person:** "You can configure..." not "Users can configure..."
- **Present tense:** "This command creates..." not "This command will create..."
- **Direct:** "Run the migration" not "You should run the migration"
- **Approachable but professional:** Avoid jargon where a plain word works

#### Structure
- Lead with the most important information
- Use headings to create scannable hierarchy
- Keep paragraphs short (3-5 sentences max)
- Use lists for steps, options, or collections of items
- Use tables for structured comparisons
- Include code examples for every API or CLI reference

#### Formatting Conventions
- **Code:** Use backticks for inline code, fenced blocks for multi-line
- **Filenames:** `monospace`
- **UI elements:** **Bold**
- **Key terms:** *Italic* on first use
- **Placeholders:** `<angle-brackets>` or `{curly-braces}` (pick one, be consistent)
- **Notes/warnings:** Use admonition blocks if supported

#### Terminology
- Create a glossary of project-specific terms
- Define preferred terms for common concepts
- List terms to avoid and their replacements

| Avoid | Prefer |
|-------|--------|
| *simply*, *just*, *easy* | *(omit — these dismiss complexity)* |
| *please* | *(omit — instructions should be direct)* |
| *click on* | *click* or *select* |
| *in order to* | *to* |

### Step 3: Code Example Standards

- Every example should be runnable or clearly marked as pseudocode
- Include language identifier in fenced code blocks
- Show complete, minimal examples (not fragments)
- Include expected output where helpful
- Use realistic but safe example data (no real emails, passwords, or keys)

### Step 4: Documentation Types

| Type | Purpose | Template |
|------|---------|----------|
| **How-to guide** | Step-by-step task completion | Goal → Prerequisites → Steps → Verification |
| **Reference** | Complete, accurate technical details | Organized by structure (alphabetical, by module) |
| **Explanation** | Understanding concepts and decisions | Context → Concept → Why → Trade-offs |
| **Tutorial** | Learning by doing | Setup → Guided steps → Working result |

## Output Format

A complete style guide document in markdown, ready to add to the project's documentation. Include examples of good and bad writing for each guideline.

## Edge Cases

- For open-source projects: include contribution guidelines for documentation PRs
- For API documentation: align with OpenAPI conventions
- For internationalized projects: note translation-friendly writing practices
- If existing docs are inconsistent: prioritize the most impactful standards first

## Quality Checklist

- [ ] Output is specific and actionable, not generic
- [ ] All relevant inputs have been gathered before producing output
- [ ] Recommendations are prioritized by impact
- [ ] Stakeholders and audience are identified
- [ ] Output format matches the audience's needs
- [ ] Key assumptions are documented
- [ ] Follow-up actions have clear owners