documentation-templates

# Documentation Templates > Templates and structure guidelines for common documentation types. --- ## 1. README Structure ### Essential Sections (Priority Order) | Section | Purpose | |---------|---------| | **Title + One-liner** | What is this? | | **Quick Start** | Running in <5 min | | **Features** | What can I do? | | **Configuration** | How to customize | | **API Reference** | Link to detailed docs | | **Contributing** | How to help | | **License** | Legal | ### README Template ```markdown # Project Name Brief one-line description. ## Quick Start [Minimum steps to run] ## Features - Feature 1 - Feature 2 ## Configuration | Variable | Description | Default | |----------|-------------|---------| | PORT | Server port | 3000 | ## Documentation - [API Reference](./docs/api.md) - [Architecture](./docs/architecture.md) ## License MIT ``` --- ## 2. API Documentation Structure ### Per-Endpoint Template ```markdown ## GET /users/:id Get a user by ID. **Parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | id | string | Yes | User ID | **Response:** - 200: User object - 404: User not found **Example:** [Request and response example] ``` --- ## 3. Code Comment Guidelines ### JSDoc/TSDoc Template ```typescript /** * Brief description of what the function does. * * @param paramName - Description of parameter * @returns Description of return value * @throws ErrorType - When this error occurs * * @example * const result = functionName(input); */ ``` ### When to Comment | ✅ Comment | ❌ Don't Comment | |-----------|-----------------| | Why (business logic) | What (obvious) | | Complex algorithms | Every line | | Non-obvious behavior | Self-explanatory code | | API contracts | Implementation details | --- ## 4. Changelog Template (Keep a Changelog) ```markdown # Changelog ## [Unreleased] ### Added - New feature ## [1.0.0] - 2025-01-01 ### Added - Initial release ### Changed - Updated dependency ### Fixed - Bug fix ``` --- ## 5. Architecture Decision Record (ADR) ```markdown # ADR-001: [Title] ## Status Accepted / Deprecated / Superseded ## Context Why are we making this decision? ## Decision What did we decide? ## Consequences What are the trade-offs? ``` --- ## 6. AI-Friendly Documentation (2025) ### llms.txt Template For AI crawlers and agents: ```markdown # Project Name > One-line objective. ## Core Files - [src/index.ts]: Main entry - [src/api/]: API routes - [docs/]: Documentation ## Key Concepts - Concept 1: Brief explanation - Concept 2: Brief explanation ``` ### MCP-Ready Documentation For RAG indexing: - Clear H1-H3 hierarchy - JSON/YAML examples for data structures - Mermaid diagrams for flows - Self-contained sections --- ## 7. Structure Principles | Principle | Why | |-----------|-----| | **Scannable** | Headers, lists, tables | | **Examples first** | Show, don't just tell | | **Progressive detail** | Simple → Complex | | **Up to date** | Outdated = misleading | --- > **Remember:** Templates are starting points. Adapt to your project's needs.