gh-codethread-claude-code-plugins-plugins-doc-writer/skills/writing-documentation/references/best-practices.md

# Documentation Best Practices & Guidelines

Synthesized from authoritative sources: Google Developer Documentation Style Guide, Diátaxis Framework, Write the Docs community, and Microsoft Writing Style Guide.

## Core Documentation Frameworks

### Diátaxis Framework
**Created by:** Daniele Procida (Canonical)
**Adopted by:** Python, Ubuntu, OpenStack, Gatsby, Cloudflare, and hundreds of other projects

**Four Interconnected Documentation Types:**

1. **Tutorials** (Learning-focused)
   - Teaches foundational concepts
   - Takes learner by the hand
   - Learning-oriented, not goal-oriented
   - Example: "Getting started with Python"

2. **How-To Guides** (Task-oriented)
   - Solves specific problems
   - Goal-oriented practical steps
   - Assumes some knowledge
   - Example: "How to configure authentication"

3. **Technical Reference** (Information-oriented)
   - Factual lookup documentation
   - Describes the machinery
   - Accurate and complete
   - Example: "API Reference"

4. **Explanation** (Understanding-oriented)
   - Conceptual understanding
   - Clarifies and enlightens
   - Provides context
   - Example: "Understanding async/await"

**Key Insight:** Mixing these types causes confusion. Keep them separate but linked.

---

## Voice and Tone (Universal Standards)

### Person, Voice, and Tense

| Element | Recommendation | Example |
|---------|----------------|---------|
| **Person** | Second person ("you") | "You can configure..." not "We can configure..." |
| **Voice** | Active voice | "The API returns JSON" not "JSON is returned" |
| **Tense** | Present tense | "The function processes..." not "will process..." |
| **Mood** | Imperative for instructions | "Click Submit" not "You should click Submit" |

**Why This Matters:**
- **Present tense:** Computers have no past/future; everything happens now
- **Active voice:** Clarifies who performs actions; easier to understand
- **Second person:** Directly addresses readers; increases engagement
- **Imperative:** More concise and direct for instructions

### Tone Characteristics

**Recommended:**
- Conversational but professional
- Friendly without being frivolous
- Warm and relaxed (Microsoft: "ready to lend a hand")
- Technically accurate without unnecessary jargon

**Avoid:**
- Overly casual language
- Humor that doesn't translate globally
- Marketing speak in technical docs
- Condescending or patronizing tone

---

## Content Organization

### Documentation Structure (Standard Pattern)

**For README/Landing Pages:**
1. **Title** (only one H1 heading)
2. **Brief description** (what and why)
3. **Installation/Setup**
4. **Quick Start** (get running in minutes)
5. **Usage examples**
6. **Features**
7. **API Reference** (or link to separate docs)
8. **Contributing/License**

**For API Documentation:**
1. **Overview** (what it does, why it exists)
2. **Authentication**
3. **Quick Start** (first successful request)
4. **Core Concepts** (key abstractions)
5. **API Reference** (endpoints, parameters, responses)
6. **Error Handling**
7. **Examples** (common use cases)

**For Tutorials:**
1. **Prerequisites** (what reader needs to know)
2. **Learning objectives** (what they'll accomplish)
3. **Step-by-step instructions**
4. **Expected output** (validate success)
5. **Next steps** (where to go from here)

### Heading Hierarchy

```markdown
# Project Title (ONLY ONE H1)

## Major Section (H2)

### Subsection (H3)

#### Sub-subsection (H4)
```

**Rules:**
- Only one H1 per page (the title)
- Don't skip heading levels (no H2 → H4)
- Use sentence case for headings
- Make headings descriptive and scannable

---

## Writing Style Guidelines

### Word Choice and Grammar

**Use:**
- Serial (Oxford) commas in lists
- Standard American spelling (if applicable)
- Descriptive link text ("See the installation guide" not "click here")
- Consistent terminology throughout
- Short, clear sentences
- Concrete examples

**Avoid:**
- Ambiguous pronouns (this, that, it without clear antecedent)
- Future tense for current features
- Passive voice when active is clearer
- Unnecessarily long words or phrases
- Jargon without definition

### Formatting Standards

**Code-related text:**
- Use `code font` for: file names, paths, variables, function names, commands
- Use **bold** for: UI elements users click, emphasis
- Use *italics* sparingly (mainly for introducing new terms)

**Lists:**
- **Numbered lists:** For sequential steps
- **Bulleted lists:** For non-sequential items
- **Description lists:** For term-definition pairs

---

## Code Examples and Documentation

### Essential Elements for Code Examples

1. **Context** - Explain what the code does and why
2. **Complete examples** - Code should be runnable (or clearly marked otherwise)
3. **Expected output** - Show what happens when code runs
4. **Comments** - Explain "why," not "what"
5. **Error handling** - Show how to handle failures

### Code Comment Quality

**Bad:** States the obvious
```javascript
i++; // increment i
const user = getUser(); // get the user
```

**Good:** Explains reasoning
```javascript
// API requires explicit null to avoid nested table joins
// We aggregate extra data in the next query
const userInfo = await externalUserApi(userId, null);
```

### API Documentation Standards

For every method/function, document:

**Parameters:**
- Name and description
- Data type
- Required vs. optional
- Default values
- Constraints (min/max, allowed values, format)

**Returns:**
- Return type
- Description of return value
- Possible return states

**Errors/Exceptions:**
- What errors can occur
- When they occur
- How to handle them

**Example:**
```javascript
/**
 * Calculates the sum of two numbers.
 *
 * @param {number} a - The first number (required)
 * @param {number} b - The second number (required)
 * @returns {number} The sum of a and b
 * @throws {TypeError} If either parameter is not a number
 *
 * @example
 * const result = sum(5, 3);
 * // Returns: 8
 *
 * @example
 * sum(5, "3"); // Throws TypeError
 */
function sum(a, b) {
  if (typeof a !== 'number' || typeof b !== 'number') {
    throw new TypeError('Both parameters must be numbers');
  }
  return a + b;
}
```

---

## Audience Awareness

### Know Your Audience

**Key Questions:**
- What is their skill level?
- What are they trying to accomplish?
- What do they already know?
- What context do they need?

**Adaptations:**
- **Beginners:** More context, fewer assumptions, step-by-step guidance
- **Intermediate:** Less hand-holding, focus on patterns and best practices
- **Advanced:** Concise reference, edge cases, performance considerations

### State Prerequisites

Always specify what readers should know before starting:

**Good:**
```markdown
## Prerequisites

Before starting this tutorial, you should have:
- Basic familiarity with JavaScript
- Node.js 18+ installed
- Understanding of REST APIs
```

**Also Good (if none):**
```markdown
## Prerequisites

This guide assumes no prior knowledge. We'll cover everything from scratch.
```

### Serve Multiple Audiences

**Techniques:**
1. **Progressive disclosure:** Basic info first, "advanced" sections clearly marked
2. **Difficulty indicators:** Label sections (beginner/intermediate/advanced)
3. **Multiple pathways:** Quick start for experienced users, detailed tutorial for beginners
4. **Collapsible sections:** Advanced details hidden until needed
5. **"If you're new to X" sidebars:** Extra context for those who need it

---

## Accessibility and Inclusivity

### Inclusive Language

**Use:**
- Gender-neutral language
- "They/their" for singular when gender unknown
- Descriptive terms, not assumptions
- Globally understood examples

**Avoid:**
- Gendered pronouns when unnecessary
- Cultural references that don't translate
- Idioms and colloquialisms
- Ableist language ("sanity check" → "validation check")

### Visual Accessibility

**Images:**
- Always include descriptive alt text
- Use high-resolution or vector images
- Ensure sufficient color contrast
- Don't rely solely on color to convey information

**Structure:**
- Clear visual hierarchy
- Sufficient whitespace
- Readable font sizes
- Responsive design for mobile

---

## Maintenance and Lifecycle

### Documentation as Code

**Principles:**
1. **Version control:** Documentation lives in git with code
2. **Review process:** Documentation PRs reviewed like code
3. **CI/CD integration:** Test documentation builds
4. **Automated testing:** Check links, code examples, formatting

### Keeping Documentation Current

**Critical Rules:**
- Update documentation in same PR as code changes
- Mark deprecated features clearly
- Date time-sensitive content
- Remove outdated content (don't just mark it)
- Regular audits for accuracy

**Warning:** Outdated documentation is worse than no documentation.

---

## Actionable Quality Checklist

### Before Publishing Documentation

- [ ] **Clarity:** Can a new user accomplish the task?
- [ ] **Accuracy:** Is all information current and correct?
- [ ] **Completeness:** Are all steps and prerequisites covered?
- [ ] **Examples:** Are there working code examples?
- [ ] **Error handling:** Are failure modes documented?
- [ ] **Navigation:** Can users find related topics easily?
- [ ] **Accessibility:** Alt text, clear headings, good contrast?
- [ ] **Consistency:** Terminology and style consistent throughout?
- [ ] **Tested:** Have you actually followed the steps?
- [ ] **Feedback:** Is there a way to report issues?

### Common Quality Issues

**Structure:**
- Missing prerequisites
- Skipping heading levels
- Too many or too few headings
- Poor information architecture

**Content:**
- Outdated examples
- Missing error documentation
- Unclear parameter descriptions
- No expected output shown

**Style:**
- Passive voice overuse
- Inconsistent terminology
- Undefined jargon
- Walls of text without breaks

---

## Documentation Maturity Model

**Level 1 - Basic:**
- Exists but scattered
- May have outdated sections
- Grammar and formatting issues
- No clear organization

**Level 2 - Structured:**
- Organized with clear headings
- Consistent formatting
- Basic separation of concerns
- Regular updates

**Level 3 - Complete:**
- Tutorials, guides, reference, and explanations
- Multiple learning pathways
- Code examples tested
- Error documentation comprehensive

**Level 4 - Maintained:**
- Updated with code changes
- Audience-aware content
- Accessible and inclusive
- Feedback mechanisms active

**Level 5 - Excellent:**
- All above plus:
- Searchable and navigable
- Multiple formats (web, PDF, etc.)
- Interactive examples
- Analytics-driven improvements
- Community contributions welcomed

---

## Quick Reference: Style Decisions

| Aspect | Recommendation |
|--------|----------------|
| **Headings** | Sentence case |
| **Lists** | Serial comma |
| **Code** | Inline `backticks` |
| **UI elements** | **Bold** |
| **Links** | Descriptive text |
| **Person** | Second person ("you") |
| **Voice** | Active |
| **Tense** | Present |
| **Tone** | Conversational, professional |
| **Paragraphs** | Short (2-4 sentences) |
| **Examples** | Required for all APIs |

---

## Sources and Further Reading

- **Google Developer Documentation Style Guide:** https://developers.google.com/style
- **Diátaxis Framework:** https://diataxis.fr/
- **Write the Docs:** https://www.writethedocs.org/guide/
- **Microsoft Writing Style Guide:** https://learn.microsoft.com/en-us/style-guide/