Documenting
Documentation Types
| Type | Audience | Content |
|---|
| README | New users | Quick start, installation, usage |
| API docs | Developers | Endpoints, parameters, responses |
| Code docs | Contributors | Architecture, patterns, decisions |
| Comments | Code readers | Why, not what |
README Structure
# Project Name
Brief description (1-2 sentences).
## Quick Start
\`\`\`bash
npm install project-name
\`\`\`
## Usage
\`\`\`typescript
import { feature } from 'project-name';
// Minimal working example
\`\`\`
## API Reference
Link to detailed docs or brief overview.
## Contributing
How to contribute, run tests, submit PRs.
## License
License type and link.
Code Comments
// Good - explains WHY
// Cache invalidated after 5 minutes to balance freshness vs API rate limits
const CACHE_TTL = 300_000;
// Bad - explains WHAT (obvious from code)
// Set cache TTL to 300000
const CACHE_TTL = 300_000;
JSDoc Format
/**
* Calculates the total price including tax.
*
* @param items - Cart items to calculate
* @param region - Tax region (affects rate)
* @returns Total price in cents
* @throws {ValidationError} If items array is empty
*
* @example
* const total = calculateTotal([{ price: 1000 }], 'EU');
* // Returns: 1210 (with 21% VAT)
*/
function calculateTotal(items: Item[], region: Region): number {
Principles
- Audience-first: Write for the reader, not yourself
- Examples over explanation: Show, don't just tell
- Keep current: Outdated docs are worse than none
- DRY: Link to existing docs, don't duplicate
- Scannable: Use headings, lists, tables
