Documentation Templates

1---
2name: documentation-templates
3description: Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.
4allowed-tools: Read, Glob, Grep
5---
6 
7# Documentation Templates
8 
9> Templates and structure guidelines for common documentation types.
10 
11---
12 
13## 1. README Structure
14 
15### Essential Sections (Priority Order)
16 
17| Section | Purpose |
18|---------|---------|
19| **Title + One-liner** | What is this? |
20| **Quick Start** | Running in <5 min |
21| **Features** | What can I do? |
22| **Configuration** | How to customize |
23| **API Reference** | Link to detailed docs |
24| **Contributing** | How to help |
25| **License** | Legal |
26 
27### README Template
28 
29```markdown
30# Project Name
31 
32Brief one-line description.
33 
34## Quick Start
35 
36[Minimum steps to run]
37 
38## Features
39 
40- Feature 1
41- Feature 2
42 
43## Configuration
44 
45| Variable | Description | Default |
46|----------|-------------|---------|
47| PORT | Server port | 3000 |
48 
49## Documentation
50 
51- [API Reference](./docs/api.md)
52- [Architecture](./docs/architecture.md)
53 
54## License
55 
56MIT
57```
58 
59---
60 
61## 2. API Documentation Structure
62 
63### Per-Endpoint Template
64 
65```markdown
66## GET /users/:id
67 
68Get a user by ID.
69 
70**Parameters:**
71| Name | Type | Required | Description |
72|------|------|----------|-------------|
73| id | string | Yes | User ID |
74 
75**Response:**
76- 200: User object
77- 404: User not found
78 
79**Example:**
80[Request and response example]
81```
82 
83---
84 
85## 3. Code Comment Guidelines
86 
87### JSDoc/TSDoc Template
88 
89```typescript
90/**
91 * Brief description of what the function does.
92 * 
93 * @param paramName - Description of parameter
94 * @returns Description of return value
95 * @throws ErrorType - When this error occurs
96 * 
97 * @example
98 * const result = functionName(input);
99 */
100```
101 
102### When to Comment
103 
104| ✅ Comment | ❌ Don't Comment |
105|-----------|-----------------|
106| Why (business logic) | What (obvious) |
107| Complex algorithms | Every line |
108| Non-obvious behavior | Self-explanatory code |
109| API contracts | Implementation details |
110 
111---
112 
113## 4. Changelog Template (Keep a Changelog)
114 
115```markdown
116# Changelog
117 
118## [Unreleased]
119### Added
120- New feature
121 
122## [1.0.0] - 2025-01-01
123### Added
124- Initial release
125### Changed
126- Updated dependency
127### Fixed
128- Bug fix
129```
130 
131---
132 
133## 5. Architecture Decision Record (ADR)
134 
135```markdown
136# ADR-001: [Title]
137 
138## Status
139Accepted / Deprecated / Superseded
140 
141## Context
142Why are we making this decision?
143 
144## Decision
145What did we decide?
146 
147## Consequences
148What are the trade-offs?
149```
150 
151---
152 
153## 6. AI-Friendly Documentation (2025)
154 
155### llms.txt Template
156 
157For AI crawlers and agents:
158 
159```markdown
160# Project Name
161> One-line objective.
162 
163## Core Files
164- [src/index.ts]: Main entry
165- [src/api/]: API routes
166- [docs/]: Documentation
167 
168## Key Concepts
169- Concept 1: Brief explanation
170- Concept 2: Brief explanation
171```
172 
173### MCP-Ready Documentation
174 
175For RAG indexing:
176- Clear H1-H3 hierarchy
177- JSON/YAML examples for data structures
178- Mermaid diagrams for flows
179- Self-contained sections
180 
181---
182 
183## 7. Structure Principles
184 
185| Principle | Why |
186|-----------|-----|
187| **Scannable** | Headers, lists, tables |
188| **Examples first** | Show, don't just tell |
189| **Progressive detail** | Simple → Complex |
190| **Up to date** | Outdated = misleading |
191 
192---
193 
194> **Remember:** Templates are starting points. Adapt to your project's needs.
195