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

# Project Name
Brief one-line description.
Quick Start
[Minimum steps to run]
Features
Feature 1

Feature 2
Configuration
<div class="overflow-x-auto my-6"><table class="min-w-full divide-y divide-border border border-border"><thead><tr><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Variable</th><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Description</th><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Default</th></tr></thead><tbody class="divide-y divide-border"><tr><td class="px-4 py-2 text-sm text-foreground">PORT</td><td class="px-4 py-2 text-sm text-foreground">Server port</td><td class="px-4 py-2 text-sm text-foreground">3000</td></tr></tbody></table></div>
Documentation
API Reference

Architecture
License
MIT

2. API Documentation Structure

Per-Endpoint Template

## GET /users/:id
Get a user by ID.
Parameters:
<div class="overflow-x-auto my-6"><table class="min-w-full divide-y divide-border border border-border"><thead><tr><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Name</th><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Type</th><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Required</th><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Description</th></tr></thead><tbody class="divide-y divide-border"><tr><td class="px-4 py-2 text-sm text-foreground">id</td><td class="px-4 py-2 text-sm text-foreground">string</td><td class="px-4 py-2 text-sm text-foreground">Yes</td><td class="px-4 py-2 text-sm text-foreground">User ID</td></tr></tbody></table></div>
Response:
200: User object

404: User not found
Example:
[Request and response example]

3. Code Comment Guidelines

JSDoc/TSDoc Template

/*
  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)

# 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)

# 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:

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