gh-sjungling-claude-plugins-plugins-technical-writer/skills/technical-writer/references/style-guide.md

# Comprehensive Technical Writing Style Guide

This reference provides detailed guidance for creating professional, accessible, and user-friendly technical documentation.

## Content Model

### Content Structure

- **Hierarchical organization**: Top-level doc sets → Categories → Map topics → Articles
- **Category creation threshold**: 10+ articles required for new categories
- **Navigation depth**: Maximum 4 levels deep
- **Consistent content types**: Each with specific purposes and formats
- **Standard elements**: Every article includes titles, intros, permissions, etc.

## Article Structure and Standard Elements

### Titles

**Character limits:**
- Categories: 67 character limit
- Map topics: 63 character limit
- Articles: 80 character limit

**Formatting:**
- Use sentence case (not title case)
- Gerund titles for procedural content ("Creating...", "Configuring...")
- Avoid "How to" prefix unless required by product convention

**Examples:**

✅ Do:
- "Set up OAuth for a single-page app"
- "Creating a service principal" (procedural/gerund)

❌ Don't:
- "Setting Up OAuth for a Single-Page App" (title case)
- "How to set up OAuth" (avoid "How to")

### Intros

**Length requirements:**
- Articles: 1-2 sentences
- Categories/Map topics: 1 sentence

**Content:**
- Must explain what the content covers
- Be specific and actionable
- Avoid vague language

**Examples:**

✅ Do:
"This guide shows you how to enable OAuth for single-page apps using PKCE. You'll configure an app, create secrets, and test the flow."

❌ Don't:
"In this document, we will be covering OAuth for single-page applications in depth." (vague, long-winded)

### Permissions Statements

**Required for:** All tasks requiring specific permissions

**Format options:**

1. **Frontmatter** (preferred):
```yaml
---
required-permissions:
  role: Owner
  scope: Subscription
---
```

2. **Inline**:
"You need the Owner role at the subscription scope to complete these steps."

**Consistency:** Use the same language patterns across documentation.

### Required Sections

When applicable, include these sections:

**Prerequisites:**
- Use structured list format
- Be specific about versions, tools, access levels

Example:
- An Azure subscription
- The Azure CLI 2.60.0 or later
- Owner role at the subscription scope

**Product callouts:**
"This feature is available on the Enterprise plan only."

**Next steps and Further reading:**
- Provide clear next actions
- Link to related content
- Use descriptive link text

## Content Types Detailed

### 1. Conceptual Content

**Purpose:** Explains what something is and why it's useful

**Characteristics:**
- "About..." article pattern
- Defines concepts and terminology
- Explains when to use and tradeoffs
- Provides context without step-by-step instructions

**Example:**
"About service principals" — defines the concept, when to use it, and tradeoffs.

### 2. Referential Content

**Purpose:** Detailed information for active use

**Characteristics:**
- Syntax guides with complete parameter lists
- Tables for complex data relationships
- Alphabetical or logical organization
- Comprehensive but scannable format

**When to use tables vs. lists:**
- **Tables**: Multiple related properties per item
- **Lists**: Simple, single-dimension information

**Structure headers appropriately:**
- Long reference content benefits from clear section breaks
- Use consistent heading hierarchy
- Enable quick scanning and search

**Example:**
"CLI reference for `az ad sp`" — flags, options, examples.

### 3. Procedural Content

**Purpose:** Step-by-step task completion

**Characteristics:**
- Numbered lists (sequential steps)
- Gerund titles ("Creating...", "Configuring...")
- One action per step
- Clear prerequisites upfront

**Step structure:**
1. Optional information (if applicable)
2. Reason for the step (if not obvious)
3. Location where to perform action
4. Action to take

**Example:**
"Creating a service principal" — numbered steps start-to-finish.

### 4. Troubleshooting Content

**Purpose:** Error resolution and known issues

**Types:**

**Known issues** (separate articles):
- Complex problems requiring detailed explanation
- Multiple potential causes
- Ongoing or unresolved issues

**General troubleshooting** (embedded):
- Common errors for specific tasks
- Quick fixes and workarounds
- Embedded in main task articles

**Structure:**
- Symptom description
- Cause explanation
- Resolution steps
- Prevention guidance

**Example:**
"Fix: AADSTS700016 error" — symptoms, cause, resolution.

### 5. Quickstart Content

**Purpose:** Essential steps for quick setup

**Critical requirements:**
- **Time limit**: 5 minutes / 600 words maximum
- **Specific intro phrasing**: Must clarify audience and scope
- **Audience clarification**: Required for complex products

**Structure:**
1. Before you begin (2-3 prerequisites)
2. Create resources (1-2 commands or clicks)
3. Run and verify (1 command or screenshot)
4. Clean up resources

**Intro pattern:**
"In this quickstart, you [accomplish X]. This guide is for [audience] who want to [goal]."

**Example:**
"Create and deploy your first function app" — 3-5 steps, done in 5 minutes.

### 6. Tutorial Content

**Purpose:** Detailed workflow guidance with real-world examples

**Requirements:**
- **Conversational tone**: Required for engagement
- **Real examples**: Must use actual, working examples (no placeholder code)
- **Conclusion structure**: Specific requirements for wrap-up

**Characteristics:**
- End-to-end scenario
- Explains "why" not just "how"
- Includes best practices
- Shows complete, working solution

**Conclusion must include:**
- Summary of what was accomplished
- Link to related concepts
- Suggested next steps
- Resources for going deeper

**Example:**
"Build a news summarizer with Functions and Cosmos DB" — end-to-end scenario.

### 7. Release Notes

**Purpose:** Version-specific changes and updates

**Requirements:**
- **Comprehensive formatting**: Specific categorization rules
- **Change categorization**: Features, fixes, improvements, breaking changes, etc.

**Categories (in order):**
1. Breaking Changes (if any)
2. Features (new capabilities)
3. Improvements (enhancements to existing features)
4. Fixes (bug fixes)
5. Documentation (doc updates)
6. Dependencies (version updates)

**Format:**
```markdown
## Version X.Y.Z - YYYY-MM-DD

### Breaking Changes
- Change description with migration path

### Features
- New feature description with brief example

### Improvements
- Enhancement description

### Fixes
- Bug fix description (can reference issue numbers)
```

**Example:**
"v1.8.0" — Features, fixes, breaking changes.

### Combining Content Types

**Guidelines:**
- Longer articles can combine multiple content types
- Follow content ordering guidelines
- Use clear transitions between sections
- Include troubleshooting information frequently

**Transition examples:**
- "Now that you understand the key concepts, follow these steps to enable the feature."
- "With the basics covered, let's explore advanced configurations."

## Content Ordering Guidelines

### Standard Content Sequence

1. **Conceptual** - What it is and why it's useful
2. **Referential** - Detailed information for active use
3. **Procedural** (in this specific order):
   - **Enabling** - Initial setup/activation
   - **Using** - Regular operational tasks
   - **Managing** - Administrative/configuration tasks
   - **Disabling** - Deactivation procedures
   - **Destructive** - Deletion/removal tasks
4. **Troubleshooting** - Error resolution

### Within Procedural Steps

Order information within each step:

1. **Optional information** (if applicable)
   - "If you already have X, skip this step."
2. **Reason** for the step (if not obvious)
   - "This keeps latency low."
3. **Location** where to perform the action
   - "In the Azure portal, go to Resource groups..."
4. **Action** to take
   - "...and select Create."

**Example:**
"Create a resource group in the same region as your app. This keeps latency low. In the Azure portal, go to Resource groups and select Create. Name it `my-rg` and select a region."

## Style Guide Key Points

### Language and Tone

**Principles:**
- Clear, simple, approachable language
- Active voice preferred (passive acceptable when appropriate)
- Sentence case for titles and headers
- Avoid jargon, idioms, regional phrases
- Write for global, multilingual audience

**Examples:**

✅ Do:
"Run the command and wait for the confirmation message."

❌ Don't:
"One could conceivably run said command prior to proceeding." (jargon, passive, unclear)

### Technical Writing Conventions

**Code formatting:**
- Use `backticks` for code, file names, commands, parameters
- Keep code blocks to ~60 character line length
- Avoid command prompts in examples (just show commands)
- Use syntax highlighting with proper language tags

**UI elements:**
- Format UI text in **bold** (buttons, menu items, fields)
- Use exact text from the interface
- Use > for navigation paths: **File > Save As**

**Placeholders:**
- ALL-CAPS with dashes: YOUR-PROJECT, YOUR-RESOURCE-GROUP
- Must explain placeholders before or after use
- Be consistent with placeholder naming

**Images:**
- Include alt text for all images (40-150 characters)
- Alt text describes what's shown, not just "screenshot"
- Reference images in text: "as shown in the following image"

**Examples:**

✅ Good:
- "Select **Create** and run `az group create --name MY-RG --location westus`."
- "Replace YOUR-RG with the name of your resource group."
- Alt text: "Screenshot of the Azure portal showing the Create resource group form with fields completed"

### Structure and Format

**Lists:**

**Numbered lists** (procedures):
- Capitalize first word
- Use periods for complete sentences
- One action per step
- Sequential order matters

**Bullet lists** (non-sequential):
- Use asterisks (*) not dashes
- Capitalize first word
- Alphabetize when appropriate
- Parallel structure

**Tables:**
- Use consistent header formatting
- Align content properly (left for text, right for numbers)
- Include header row
- Keep cells concise

**Alert Types** (use sparingly):

- **Note**: Neutral, supplementary information
  - "The CLI caches credentials for 1 hour."
- **Tip**: Helpful shortcuts or best practices
  - "Use tags to organize resources across subscriptions."
- **Important**: Critical information that affects outcomes
  - "Do not share client secrets. Rotate them every 90 days."
- **Warning**: Potential risks or consequences
  - "Deleting the resource group removes all resources in it."
- **Caution**: Actions that could cause data loss or damage
  - "Export data before disabling the feature to avoid loss."

### Links and References

**Internal links:**
- Use appropriate formatting for your doc system
- Link to specific sections when helpful
- Keep link text descriptive

**Link text:**
- Be descriptive (tell what user will find)
- Never use "click here" or "read more"
- Include context when needed

**External links:**
- Provide full context
- Explain why user should follow the link
- Consider link rot (prefer stable URLs)

**Examples:**

✅ Do:
- "See the authentication overview for background on OAuth 2.0."
- "For the OAuth 2.1 draft, see the IETF working group page."

❌ Don't:
- "Click here for more info."
- "Read more." (no context)

## Process and Workflow Elements

### Topics (Metadata)

**Character limits:**
- Keep topics concise
- Follow selection criteria for your platform

**Forbidden patterns:**
- Avoid duplicating title text
- Don't use as keyword stuffing

### Tool Switchers

**When to use:**
- Multiple interfaces for same task (Portal, CLI, PowerShell, Terraform)
- All methods achieve same outcome
- Each deserves equal treatment

**Format:**
- Use tabbed interface when supported
- Consistent ordering across docs
- Complete examples in each tab

**Example:**
"Portal | CLI | PowerShell | Terraform"

### Call to Action (CTA)

**Requirements:**
- Consistent formatting
- Clear, action-oriented language
- Specific next step

**Examples:**
- Next steps: "Next, secure your API keys with Key Vault."
- CTA button text: "Save", "Create", "Deploy" (not "Click to save")

### Reusables and Variables

**When to use reusables:**
- Content repeated verbatim across multiple articles
- Maintenance efficiency matters
- Content unlikely to need article-specific variations

**When to inline content:**
- Article-specific variations likely
- Better readability in source
- Single-use content

**Variable usage:**
- Define at document start or first use
- Be consistent with variable names
- Match placeholder conventions

**Examples:**
- "Set `YOUR-RG`, `YOUR-LOCATION`, and `YOUR-APP-NAME`."
- Reusable snippet: Common troubleshooting block for network timeouts

## Accessibility Requirements

### Alt Text

**Requirements:**
- 40-150 characters
- Describe what's shown, not "screenshot of..."
- Include relevant text from image
- Convey information, not aesthetics

**Examples:**
✅ "Azure portal showing the Create resource group form with fields completed"
❌ "Screenshot" (too vague)

### Structure

**Heading hierarchy:**
- Use proper heading levels (H1 → H2 → H3)
- Don't skip levels
- One H1 per page (the title)

**Reading order:**
- Content makes sense when read linearly
- Screen reader compatible

**Color and contrast:**
- Don't rely on color alone
- Ensure sufficient contrast
- Use patterns or labels in addition to color

### Links

**Descriptive link text:**
- Tells where link goes
- Makes sense out of context
- Avoid "click here"

### ARIA (when applicable)

- Use ARIA labels for complex interactions
- Ensure keyboard navigation works
- Test with screen readers

## Localization Considerations

**Write for translation:**
- Avoid idioms and colloquialisms
- Use simple sentence structure
- Be explicit (avoid implied information)
- Watch for cultural references

**Date and number formatting:**
- Use international formats
- Provide context for ambiguous formats
- Let localization system handle conversion

**Right-to-left (RTL) languages:**
- Ensure UI accommodates RTL
- Test with RTL languages
- Avoid directional language ("left sidebar")

**String externalization:**
- Use localization keys
- Avoid concatenating strings
- Plan for text expansion (some languages are longer)

## Quality Checklist

Use this checklist before publishing:

**Content:**
- [ ] Accurate and technically correct
- [ ] Appropriate content type for task
- [ ] Complete (no missing steps or information)
- [ ] Examples work as documented
- [ ] Tone appropriate for audience

**Structure:**
- [ ] Clear title (sentence case, within character limits)
- [ ] Brief intro (1-2 sentences)
- [ ] Prerequisites listed when needed
- [ ] Logical flow and organization
- [ ] Clear next steps

**Style:**
- [ ] Sentence case for headers
- [ ] Active voice (mostly)
- [ ] Code formatted correctly
- [ ] Placeholders explained
- [ ] Links descriptive and working

**Accessibility:**
- [ ] Alt text for all images
- [ ] Proper heading hierarchy
- [ ] Sufficient color contrast
- [ ] Keyboard accessible

**Polish:**
- [ ] Spell check passed
- [ ] Grammar correct
- [ ] Consistent terminology
- [ ] No jargon or explained when necessary

## Summary: Quick Decision Tree

**What type of content do I need?**

- Explaining a concept? → **Conceptual**
- Documenting API/syntax? → **Referential**
- How to do a task? → **Procedural**
- Fixing errors? → **Troubleshooting**
- Quick start (< 5 min)? → **Quickstart**
- Learning journey? → **Tutorial**
- Version changes? → **Release Notes**

**How should I structure it?**

1. Title (sentence case, descriptive)
2. Intro (1-2 sentences, specific)
3. Prerequisites (if needed)
4. Main content (type-appropriate)
5. Troubleshooting (when helpful)
6. Next steps

**What voice should I use?**

- Active, direct, clear
- Simple language
- Appropriate for global audience
- Professional but approachable

**Did I make it accessible?**

- Alt text on images
- Proper headings
- Descriptive links
- Sufficient contrast