Technical Documentation

Provide structured patterns for creating technical documentation including README, design documents, API specifications, and user guides for diverse audiences. Write - Create new documentation files Edit - Update existing documentation Read - Review existing documentation and code Grep - Search for patterns across documentation Glob - Find related documentation files Four primary types: README (project intro), API spec (endpoints/interfaces), design doc (architecture decisions), user guide (end-user tutorials) Developer (technical depth), team member (context + depth), end user (no jargon, step-by-step) Start with quick start, then common cases, then advanced config, finally edge cases Plan (outline) → Draft (write + examples) → Review (verify accuracy) → Maintain (update with code) Project introduction and quick start guide Is this the main entry point for project documentation? Create README with quick start and overview</if_yes> Consider using design doc for detailed architecture or user guide for end-user documentation</if_no> </decision_tree> Developers, contributors, users Creating or updating main project documentation</when_to_use>

Project title and badges

One-line description

Key features (3-5 bullet points)

Quick start / Installation

Basic usage example

Documentation links

Contributing / License

API reference documentation Are you documenting API endpoints or SDK interfaces? Create API specification with authentication, endpoints, and examples</if_yes> Use README for library usage or design doc for internal architecture</if_no> </decision_tree> Developers integrating with the API Documenting REST APIs, GraphQL schemas, or SDK interfaces</when_to_use>

Overview and authentication

Base URL and versioning

Endpoints (method, path, parameters, response)

Error codes and handling

Rate limits

Examples (curl, language-specific)

Technical design and architecture documentation Are you proposing a major feature or architectural change? Create design document with technical details, alternatives, and rollout plan</if_yes> Use inline code comments for small changes or README for usage instructions</if_no> </decision_tree> Team members, reviewers, future maintainers Proposing new features, architectural changes, or major refactors</when_to_use>

Summary (problem, solution, scope)

Background and motivation

Goals and non-goals

Technical design (architecture, data flow)

Alternatives considered

Security / Privacy considerations

Testing strategy

Rollout plan

End-user facing documentation Is your audience non-technical end users? Create user guide with step-by-step tutorials and troubleshooting</if_yes> Use API docs for developers or README for contributors</if_no> </decision_tree> Non-technical users, administrators Creating help documentation, tutorials, or product guides</when_to_use>

Getting started

Core concepts

Step-by-step tutorials

Feature reference

Troubleshooting / FAQ

Glossary

Standard structure for README documentation Project Name

  [![Badge](https://img.shields.io/badge/example-badge-blue)]

  Brief one-line description of what the project does.

  <features>
    - Feature 1
    - Feature 2
    - Feature 3
  </features>

  <quick_start>
    ```bash
    npm install package-name
    ```
  </quick_start>

  <basic_usage>
    ```typescript
    import { example } from "package-name";

    const result = example();
    console.log(result);
    ```
  </basic_usage>

  <documentation>
    See [full documentation](link) for detailed guides.
  </documentation>

  <contributing>
    Contributions welcome! See [CONTRIBUTING.md](link).
  </contributing>

  <license>
    MIT
  </license>
</example>

Comprehensive API reference documentation structure API Reference

  <authentication>
    All requests require an API key in the Authorization header:

    ```bash
    Authorization: Bearer YOUR_API_KEY
    ```
  </authentication>

  <base_url>
    ```
    https://api.example.com/v1
    ```
  </base_url>

  <endpoints>
    <get_users>
      Retrieve a list of users.

      **Parameters:**

      - `limit` (integer, optional): Number of results (default: 10)
      - `offset` (integer, optional): Pagination offset (default: 0)

      **Response:**

      ```json
      {
        "users": [
          { "id": 1, "name": "John Doe" },
          { "id": 2, "name": "Jane Smith" }
        ],
        "total": 100
      }
      ```

      **Error Codes:**

      - `401`: Unauthorized - Invalid API key
      - `429`: Rate limit exceeded
    </get_users>
  </endpoints>
</example>

Technical design document format for architectural decisions Feature Name Design Document

  <summary>
    **Problem:** Brief description of the problem being solved
    **Solution:** High-level approach
    **Scope:** What's included and what's not
  </summary>

  <background>
    Context and motivation for this design.
  </background>

  <goals_and_non_goals>
    **Goals:**

    - Goal 1
    - Goal 2

    **Non-Goals:**

    - What we're explicitly not doing
    - Future considerations
  </goals_and_non_goals>

  <technical_design>
    <architecture>
      [Diagram or description of system architecture]
    </architecture>

    <data_flow>
      1. User action
      2. System processing
      3. Response
    </data_flow>

    <components>
      **Component A:** Responsible for X
      **Component B:** Responsible for Y
    </components>
  </technical_design>

  <alternatives_considered>
    <alternative_1>
      Pros: ...
      Cons: ...
      Decision: Not chosen because...
    </alternative_1>
  </alternatives_considered>

  <security_considerations>
    - Data encryption at rest and in transit
    - Authentication and authorization
    - Input validation
  </security_considerations>

  <testing_strategy>
    - Unit tests for component logic
    - Integration tests for API contracts
    - E2E tests for critical user flows
  </testing_strategy>

  <rollout_plan>
    1. Phase 1: Internal testing
    2. Phase 2: Beta release (10% of users)
    3. Phase 3: Full rollout
  </rollout_plan>
</example>

End-user documentation with step-by-step instructions User Guide

  <getting_started>
    Welcome! This guide will help you get started with [Product Name].
  </getting_started>

  <core_concepts>
    **Workspace:** A container for your projects
    **Project:** A collection of related items
    **Item:** The basic unit of work
  </core_concepts>

  <creating_your_first_project>
    1. Click the "New Project" button
    2. Enter a project name
    3. Choose a template (optional)
    4. Click "Create"

    You'll see your new project in the sidebar.
  </creating_your_first_project>

  <troubleshooting>
    <troubleshooting_login>
      1. Check your email address is correct
      2. Click "Forgot Password" to reset
      3. Contact support if the issue persists
    </troubleshooting_login>

    <troubleshooting_data>
      Ensure you have a stable internet connection. The app auto-saves every 30 seconds.
    </troubleshooting_data>
  </troubleshooting>

  <glossary>
    **Term:** Definition
    **Another Term:** Another definition
  </glossary>
</example>

Audience-first approach - Write for your specific audience's knowledge level Developers: Assume technical background, focus on implementation details Team members: Balance context with technical depth End users: Avoid jargon, use step-by-step instructions Progressive disclosure - Start with essentials, reveal complexity gradually 1. Quick start for immediate value 2. Common use cases 3. Advanced configuration 4. Edge cases and troubleshooting Make content scannable to enable quick information retrieval - Use descriptive headings - Use bullet points for lists - Include code blocks with syntax highlighting - Use tables for structured data - Use bold for key terms (sparingly) Example-driven documentation - Show, don't just tell - Include working code examples - Show expected output - Provide copy-pasteable commands Active voice and present tense for clarity Good: Run this command to start the server. Bad: The server can be started by running the following command. Test all code examples before publishing Always verify that code examples compile and run correctly Include expected output Test edge cases mentioned in documentation </best_practices> <style>Active voice, present tense</style> Professional but approachable Unnecessarily complex words, idioms that don't translate Good</good_example> Run this command to start the server.

  <bad_example>Bad</bad_example>
  The server can be started by running the following command.
</example>

<style>です・ます調 (polite form) for user docs, である調 for technical specs</style> 丁寧だが簡潔 過度なカタカナ語、曖昧な表現 Good</good_example> 以下のコマンドでサーバーを起動します。

  <bad_example>Bad</bad_example>
  サーバーの起動については、下記コマンドを実行することで可能となります。
</example>

Maintain parallel structure between languages Keep code examples identical, translate only prose Use consistent terminology (create glossary if needed) </language_guidelines> - Type: [readme/api_spec/design_doc/user_guide] - Audience: [developer/team/end_user] - Language: [en/ja/both] </document_plan>

<structure>
  [Proposed sections based on document type]
</structure>

<content>
  [Actual documentation content]
</content>

<review_checklist>
  - [ ] Technical accuracy verified
  - [ ] Code examples tested
  - [ ] Links working
  - [ ] Appropriate for audience
  - [ ] Grammar and spelling checked
</review_checklist>

Long paragraphs without formatting Break into smaller paragraphs, use bullet points, headings, and code blocks Documenting historical context instead of current state Document what exists now, move history to a separate section if needed Using terms or concepts without definition Define terms on first use, link to prerequisites, provide glossary Including code examples that haven't been tested Always verify code examples compile and run correctly before publishing Using passive constructions that obscure agency Use active voice for clarity (e.g., "Run the command" not "The command should be run") Using technical jargon without explanation Define technical terms on first use, provide a glossary, or use simpler language for user-facing docs Assuming users have required knowledge or setup List prerequisites clearly at the beginning, link to setup guides Using imprecise language like "simply" or "just" without concrete steps Provide specific, numbered steps with expected outcomes </anti_patterns> Verify all code examples compile and run before including in documentation Match documentation structure to audience knowledge level Never publish documentation with placeholder content or TODOs Use active voice and present tense for instructions Include expected output for all code examples Define technical terms on first use or link to glossary Keep README under 500 lines; link to detailed docs for more Minor formatting inconsistency Fix formatting, follow style guide Outdated information detected Update content, verify with code Incorrect technical information Stop, verify with implementation before publishing Security-sensitive information exposed Block publication, require security review </error_escalation> Verify accuracy against actual implementation Include runnable code examples Follow project documentation style Documenting without reading code Adding timestamps to documents Duplicating information unnecessarily Symbol operations for extracting code examples and API signatures Library documentation lookup for accurate API references Analyzing codebases to understand features for documentation Creating blog posts and tutorials from documentation </related_skills>