319 Documentation Standards 742eb0b0

Documentation Standards

Core Principles

1. Living Documentation

• Documentation stays current with code
• Update docs in the same PR as code changes
• Living docs (README, CLAUDE, AGENTS) updated regularly
• Outdated information removed promptly

2. Clarity & Accessibility

• Write for beginners, not experts
• Use simple, clear language
• Provide examples for all concepts
• Include troubleshooting sections

3. Structure & Consistency

• Follow established templates
• Use consistent formatting
• Maintain clear hierarchy
• Keep related content together

File Naming Conventions

General Rules

# Markdown files
README.md           # Repository root (UPPERCASE)
CLAUDE.md           # Repository root (UPPERCASE)
AGENTS.md           # Repository root (UPPERCASE)
CHANGELOG.md        # Repository root (UPPERCASE)
LICENSE             # Repository root (no extension)

# Other documentation (lowercase with hyphens)
installation-guide.md
user-guide.md
api-reference.md
troubleshooting.md

Directory-Specific Naming

# Agents (lowercase with hyphens)
agents/marketing/cs-content-creator.md
agents/c-level/cs-ceo-advisor.md

# Skills (lowercase, no hyphens in folder names)
marketing-skill/content-creator/SKILL.md

# Standards (lowercase with hyphens)
standards/communication/communication-standards.md

# Documentation (lowercase with hyphens)
documentation/implementation/implementation-plan-november-2025.md
documentation/delivery/sprint-11-05-2025/context.md

Markdown Formatting Standards

1. Headings

# H1 - Document Title (only one per file)

## H2 - Major Sections

### H3 - Subsections

#### H4 - Details

**Don't skip heading levels!**
✅ H1 → H2 → H3
❌ H1 → H3 (skips H2)

2. Lists

# Unordered lists
- Item 1
- Item 2
  - Sub-item 2.1
  - Sub-item 2.2
- Item 3

# Ordered lists
1. First step
2. Second step
3. Third step

# Task lists
- [ ] Incomplete task
- [x] Completed task

3. Code Blocks

# Inline code
Use `code` for commands, filenames, and variables.

# Code blocks with syntax highlighting
\`\`\`bash
# Bash commands
git commit -m "feat(agents): implement cs-content-creator"
\`\`\`

\`\`\`python
# Python code
def analyze_content(text: str) -> Dict[str, Any]:
    return {"score": 0.85}
\`\`\`

\`\`\`yaml
# YAML configuration
name: cs-content-creator
domain: marketing
\`\`\`

4. Links

# External links
[Link text](https://example.com)

# Internal links (relative paths)
[Agent catalog](agents/README.md)
[Installation guide](INSTALL.md)

# Link to specific heading
[See quality standards](#quality-standards)

# Reference-style links (for repeated URLs)
[Claude Code][1]
[GitHub][2]

[1]: https://claude.com/code
[2]: https://github.com

5. Images

# Standard image
![Alt text describing image](path/to/image.png)

# Image with title
![Alt text](image.png "Image title")

# Linked image
[![Alt text](image.png)](https://link-destination.com)

**Always provide alt text for accessibility!**

6. Tables

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
| Data 4   | Data 5   | Data 6   |

# Alignment
| Left | Center | Right |
|:-----|:------:|------:|
| L1   |   C1   |    R1 |

7. Emphasis

*Italic text* or _italic text_
**Bold text** or __bold text__
***Bold and italic*** or ___bold and italic___
~~Strikethrough~~

Use **bold** for emphasis, *italic* for definitions.

8. Blockquotes

> Single line quote

> Multi-line quote
> continues here
> and here

> **Note:** Important information
> highlighted in a quote block

9. Horizontal Rules

---

Use sparingly to separate major sections.

Document Structure Templates

Agent Documentation (agents//cs-.md)

---
name: cs-agent-name
description: One-line description
skills: skill-folder-name
domain: domain-name
model: sonnet
tools: [Read, Write, Bash, Grep, Glob]
---

# Agent Name

## Purpose
[1-2 paragraphs describing what this agent does]

## Skill Integration

**Skill Location:** `../../skill-folder/`

### Python Tools
[List with usage examples]

### Knowledge Bases
[List with relative paths]

### Templates
[List with relative paths]

## Workflows

### Workflow 1: [Name]
[Step-by-step process]

### Workflow 2: [Name]
[Step-by-step process]

## Integration Examples
[Concrete examples with code]

## Success Metrics
[How to measure effectiveness]

## Related Agents
[Links to related agents]

## References
[Links to documentation]

README.md Structure

# Project Title

[1-sentence project description]

## Quick Start

[Installation and first use - 30 seconds]

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

[Detailed installation steps]

## Usage

[Basic usage examples]

## Documentation

- [Installation Guide](INSTALL.md)
- [Usage Guide](USAGE.md)
- [Agent Catalog](agents/README.md)

## Contributing

[Contribution guidelines]

## License

[License information]

SKILL.md Structure

# Skill Name

[1-2 paragraph description]

## What This Skill Does

[Clear explanation of purpose and value]

## Contents

- Python Tools (X scripts)
- Knowledge Bases (X references)
- Templates (X templates)

## Python Automation Tools

### Tool 1: [Name]
**Purpose:** [What it does]
**Usage:**
\`\`\`bash
python scripts/tool-name.py input.txt
\`\`\`

## Knowledge Bases

### Reference 1: [Name]
**Location:** `references/file-name.md`
**Content:** [What's inside]

## Templates

### Template 1: [Name]
**Location:** `assets/template-name.md`
**Use Case:** [When to use]

## Examples

[Real-world usage examples]

## Requirements

- Python 3.8+
- Standard library only (or list dependencies)

## Installation

[How to use this skill]

## Related Skills

[Links to related skills]

Living Documentation

Files That Must Stay Current

repository_root:
  README.md:
    update_frequency: "Every major feature"
    purpose: "Primary project documentation"
    audience: "All users"

  CLAUDE.md:
    update_frequency: "Every structural change"
    purpose: "AI context and architecture"
    audience: "Claude Code and developers"

  AGENTS.md:
    update_frequency: "Every agent added/modified"
    purpose: "Agent catalog and reference"
    audience: "Agent developers"

  CHANGELOG.md:
    update_frequency: "Every release"
    purpose: "Version history and changes"
    audience: "All users"

Update Triggers

update_readme_when:
  - New skill added
  - New agent implemented
  - Installation process changes
  - Major feature added

update_claude_md_when:
  - Directory structure changes
  - Architecture changes
  - New standards added
  - Agent integration patterns change

update_agents_md_when:
  - New agent created
  - Agent modified
  - Agent deprecated
  - Agent template changes

Quality Checklist

Pre-Commit Documentation Review

content_quality:
  - [ ] All headings follow hierarchy (no skipped levels)
  - [ ] All code blocks have syntax highlighting
  - [ ] All links work (no 404s)
  - [ ] All images have alt text
  - [ ] No spelling errors
  - [ ] Grammar is correct
  - [ ] Examples are tested and working

formatting:
  - [ ] Consistent heading style
  - [ ] Consistent list formatting
  - [ ] Consistent code block style
  - [ ] No trailing whitespace
  - [ ] Single blank line between sections
  - [ ] Proper indentation

accessibility:
  - [ ] Alt text describes images meaningfully
  - [ ] Link text is descriptive (not "click here")
  - [ ] Heading hierarchy is logical
  - [ ] Tables have headers
  - [ ] Color is not the only way to convey information

Link Validation

# Check for broken markdown links
find . -name "*.md" -exec grep -l "](.*)" {} \; | while read file; do
    echo "Checking links in: $file"
    # Manual check or use markdown-link-check tool
done

Documentation Best Practices

Do's

• ✅ Write for the target audience
• ✅ Use clear, simple language
• ✅ Provide concrete examples
• ✅ Include screenshots where helpful
• ✅ Update docs with code changes
• ✅ Link to related documentation
• ✅ Use consistent terminology
• ✅ Test all code examples

Don'ts

• ❌ Assume prior knowledge
• ❌ Use jargon without explanation
• ❌ Write vague instructions
• ❌ Skip error scenarios
• ❌ Let docs get stale
• ❌ Use "click here" as link text
• ❌ Skip proofreading
• ❌ Forget about mobile users

Special Documentation Types

API Documentation

## Function Name

**Purpose:** What this function does

**Parameters:**
- `param1` (type): Description
- `param2` (type, optional): Description, default: value

**Returns:**
- (type): Description of return value

**Raises:**
- `ExceptionName`: When this is raised

**Example:**
\`\`\`python
result = function_name(param1="value", param2=42)
print(result)
# Output: expected output
\`\`\`

Troubleshooting Guide

## Problem: [Describe the problem]

**Symptoms:**
- Symptom 1
- Symptom 2

**Cause:**
[What causes this issue]

**Solution:**
1. Step 1
2. Step 2
3. Step 3

**Verification:**
[How to confirm it's fixed]

Decision Records

# Decision: [Title]

**Date:** YYYY-MM-DD
**Status:** Accepted | Rejected | Superseded

## Context
[What's the situation?]

## Decision
[What did we decide?]

## Rationale
[Why did we decide this?]

## Consequences
[What are the impacts?]

## Alternatives Considered
1. Alternative 1 - [Why rejected]
2. Alternative 2 - [Why rejected]

Focus: Markdown quality, structure consistency, living documentation Updated: November 2025 Review: Monthly documentation quality assessment Compliance: Markdown standards, accessibility guidelines