technical-documentation

name	Technical Documentation
description	This skill should be used when the user asks to "write documentation", "create README", "API docs", "design document", "specification", "user guide", or needs documentation guidance. Provides comprehensive documentation patterns for developers, teams, and end-users in both English and Japanese.
version	0.1.0

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 Project introduction and quick start guide Developers, contributors, users Creating or updating main project documentation

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 Developers integrating with the API Documenting REST APIs, GraphQL schemas, or SDK interfaces

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 Team members, reviewers, future maintainers Proposing new features, architectural changes, or major refactors

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 Non-technical users, administrators Creating help documentation, tutorials, or product guides

Getting started

Core concepts

Step-by-step tutorials

Feature reference

Troubleshooting / FAQ

Glossary

Standard structure for README documentation Project Name

[]

Brief one-line description of what the project does.

• Feature 1
• Feature 2
• Feature 3

npm install package-name

import { example } from "package-name";

const result = example();
console.log(result);

See full documentation for detailed guides.

Contributions welcome! See CONTRIBUTING.md.

MIT

Comprehensive API reference documentation structure API Reference

All requests require an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

https://api.example.com/v1

<get_users>

Retrieve a list of users.

Parameters:

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

Response:

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

Error Codes:

• 401: Unauthorized - Invalid API key
• 429: Rate limit exceeded

Technical design document format for architectural decisions Feature Name Design Document

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

Context and motivation for this design.

Goals:

• Goal 1
• Goal 2

Non-Goals:

• What we're explicitly not doing
• Future considerations

[Diagram or description of system architecture]

1. User action
2. System processing
3. Response

Component A: Responsible for X Component B: Responsible for Y

<alternative 1>

Pros: ... Cons: ... Decision: Not chosen because...

• Data encryption at rest and in transit
• Authentication and authorization
• Input validation

• Unit tests for component logic
• Integration tests for API contracts
• E2E tests for critical user flows

1. Phase 1: Internal testing
2. Phase 2: Beta release (10% of users)
3. Phase 3: Full rollout

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

Welcome! This guide will help you get started with [Product Name].

Workspace: A container for your projects Project: A collection of related items Item: The basic unit of work

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.

<troubleshooting_login>

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

<troubleshooting_data>

Ensure you have a stable internet connection. The app auto-saves every 30 seconds.

Term: Definition Another Term: Another definition

<best_practices> 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

<language_guidelines>

Active voice, present tense

Professional but approachable Unnecessarily complex words, idioms that don't translate

<good_example>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.

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

<bad_example>Bad</bad_example>

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

Maintain parallel structure between languages Keep code examples identical, translate only prose Use consistent terminology (create glossary if needed) Identify document type and audience Outline key sections Gather technical details Write in order: overview → details → examples Include all code examples (test them) Mark TODOs for uncertain parts Verify technical accuracy Check all links and code examples work Review for audience appropriateness Proofread for grammar and typos Update when code changes Review periodically for accuracy Track user feedback

• Type: [readme/api_spec/design_doc/user_guide]
• Audience: [developer/team/end_user]
• Language: [en/ja/both]

[Proposed sections based on document type]

[Actual documentation content]

• Technical accuracy verified
• Code examples tested
• Links working
• Appropriate for audience
• Grammar and spelling checked

<anti_patterns> 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