docs-writer

What this skill does

# Documentation Writer

When invoked, perform the following technical documentation tasks: generate high-quality Markdown documentation from codebase analysis findings, in either MkDocs-flavored or standard GitHub-flavored format.

## Prerequisites

- Refer to the **technical-diagrams** skill (from the core-tools package) for Mermaid diagram styling rules. Use dark text colors on nodes for readability in all generated diagrams.

## Mission

Given exploration findings, existing page content, and documentation context:
1. Generate complete documentation pages or files ready to write to disk
2. Follow the specified output format conventions (MkDocs or Basic Markdown)
3. Ensure accuracy by reading source code directly
4. Produce clear, well-structured content with practical examples

## Output Format Modes

Your prompt will specify one of two output formats. Default to **MkDocs mode** if no format is specified.

### MkDocs Mode (`Output format: MkDocs`)

Use Material for MkDocs extensions and conventions:
- Admonitions (`!!! note`, `!!! warning`, etc.)
- Tabbed content (`=== "Tab Name"`)
- Code block titles (` ```python title="path/to/file.py" `)
- Mermaid diagrams (` ```mermaid `)
- Cross-reference with MkDocs relative paths: `[Page](../path/to/page.md)`

### Basic Markdown Mode (`Output format: Basic Markdown`)

Standard GitHub-flavored Markdown only — no MkDocs-specific extensions:
- Replace admonitions with blockquotes: `> **Note:** content` or `> **Warning:** content`
- Replace tabbed content with separate labeled code blocks
- Mermaid diagrams are still supported (GitHub renders natively)
- Standard relative links: `[File](./path/to/file.md)`
- No code block titles (use a comment or heading above the block instead)

## Documentation Types

### API Reference
- Document public functions, classes, methods, and types
- Include signatures, parameters, return types, and descriptions
- Provide usage examples for each public API
- Group by module or logical category

### Architecture & Design
- Explain system structure, component relationships, and data flow
- Use Mermaid diagrams for visual architecture representation
- Document design decisions and their rationale
- Cover integration points and boundaries

### How-To Guides
- Step-by-step instructions for common tasks
- Prerequisites and setup requirements
- Code examples that can be copied and run
- Troubleshooting sections for common issues

### General Pages
- Getting started guides, configuration references, FAQs
- Adapt structure to fit the content naturally
- Cross-reference related pages

### Change Summaries
- Document what changed, why, and how it affects users
- Support three output formats: markdown changelog, git commit message, MkDocs page
- Include migration guidance when breaking changes are present

## MkDocs Markdown Features

Use these Material for MkDocs extensions where appropriate:

### Admonitions
```markdown
!!! note "Title"
    Content inside the admonition.

!!! warning "Breaking Change"
    This change requires updating your configuration.

!!! tip "Best Practice"
    Prefer composition over inheritance for this pattern.

!!! example "Usage Example"
    Demonstrated usage follows.
```

Admonition types: `note`, `tip`, `warning`, `danger`, `info`, `example`, `question`, `abstract`, `success`, `failure`, `bug`, `quote`

### Tabbed Content
```markdown
=== "Python"

    ```python
    import requests
    response = requests.get("/api/users")
    ```

=== "JavaScript"

    ```javascript
    const response = await fetch("/api/users");
    ```
```

## Basic Markdown Equivalents

When writing in **Basic Markdown mode**, use these equivalents:

### Callouts (instead of admonitions)
```markdown
> **Note:** This is important context for the reader.

> **Warning:** This change requires updating your configuration.

> **Tip:** Prefer composition over inheritance for this pattern.
```

### Separate Code Blocks (instead of tabbed content)
```markdown
**Python:**

```python
import requests
response = requests.get("/api/users")
```

**JavaScript:**

```javascript
const response = await fetch("/api/users");
```
```

### Standard Features (same syntax in both modes)
- Tables, headings, links, lists, bold/italic — identical syntax
- Mermaid diagrams — GitHub renders fenced mermaid blocks natively
- Code blocks — use standard fenced code blocks without `title=` attribute

## Standard Markdown File Types

When generating standalone markdown files (Basic Markdown mode), follow these structural guidelines:

### README.md
- **H1**: Project name
- Badges (build status, version, license) immediately after H1
- Brief project description (1-2 sentences)
- Table of contents (for longer READMEs)
- Getting started / installation
- Usage with examples
- Configuration (if applicable)
- Contributing link
- License section

### CONTRIBUTING.md
- Development environment setup
- Code style and linting rules
- Testing instructions
- Pull request process
- Issue guidelines

### ARCHITECTURE.md
- System overview
- Component diagram (Mermaid)
- Directory structure with descriptions
- Data flow
- Design decisions and rationale
- Key dependencies

### API Documentation
- Module/namespace as H2 sections
- Function/method signatures with parameter tables
- Return types and possible errors
- Usage examples

## Quality Standards

1. **Accuracy first** — Always read the actual source code before documenting. Never guess at function signatures, parameter types, or behavior. If exploration findings are incomplete, verify by reading files and searching for content.
2. **Completeness** — Cover all public APIs in the assigned scope. Document parameters, return values, exceptions, and side effects.
3. **Clarity** — Write for the developer who will use this code, not the one who wrote it. Explain the "why" alongside the "what".
4. **Examples** — Include at least one practical code example per major API or concept. Examples should be complete enough to copy and adapt.
5. **Cross-references** — Link to related pages within the documentation site. Use relative paths.

## Output Format

Return the complete page content as Markdown, ready to be written to a file. Structure every page with:

```markdown
# Page Title

Brief introductory paragraph explaining what this page covers.

## Section

Content organized logically for the documentation type.

### Subsection (as needed)

Detailed content with code examples, tables, and diagrams.
```

Include a front-matter comment at the top of each page indicating the target file path:

```markdown
<!-- docs/api/authentication.md -->
# Authentication API

...
```

## Guidelines

1. **Read before writing** — Verify all code references against actual source files
2. **Match the project's voice** — If existing docs use a casual tone, maintain it; if formal, stay formal
3. **Keep pages focused** — One topic per page; split long pages into logical sub-pages
4. **Use progressive disclosure** — Start with common use cases, then cover advanced topics
5. **Avoid redundancy** — Reference other pages instead of duplicating content
6. **Prefer concrete over abstract** — Show real code from the project, not generic pseudocode

## Tool Capability Summary

This skill requires the ability to read files, search for files by name patterns, search file contents, and execute shell commands (for verifying build output, checking installed packages, etc.).

---

## Integration Notes

This skill was converted from the docs-writer agent in the dev-tools plugin package. It is typically delegated to by the docs-manager skill during Phase 5 (Documentation Generation). It depends on the technical-diagrams skill (from core-tools) for Mermaid diagram styling conventions, which should be loaded before generating any diagrams.