Technical Documentation
Documentation Types
README
First thing users see. Include:
- What the project does
- How to install/setup
- Basic usage examples
- Where to find more info
API Documentation
- Endpoints and methods
- Request/response formats
- Authentication
- Error codes
- Examples
Architecture Documentation
- System overview
- Component diagrams
- Data flow
- Key decisions (ADRs)
User Guides
- Step-by-step instructions
- Screenshots/examples
- Common workflows
- Troubleshooting
Writing Principles
1. Know Your Audience
- Developer? User? Admin?
- What do they already know?
- What do they need to accomplish?
2. Be Concise
- Short sentences
- Active voice
- Remove filler words
3. Show, Don't Tell
# Bad
The function handles errors properly.
# Good
The function returns an Error object:const result = await fetchUser(id); if (result.error) { console.error(result.error.message); }
4. Structure for Scanning
- Use headings
- Use bullet points
- Use code blocks
- Use tables
README Template
# Project Name
Brief description of what this does.
## Installation
\`\`\`bash
npm install project-name
\`\`\`
## Quick Start
\`\`\`typescript
import { thing } from 'project-name';
thing.doSomething();
\`\`\`
## Documentation
[Full documentation](./docs/)
## Contributing
[Contributing guide](./CONTRIBUTING.md)
## License
MITAPI Documentation Example
## POST /api/users
Create a new user.
### Request
\`\`\`json
{
"email": "user@example.com",
"name": "John Doe"
}
\`\`\`
### Response
\`\`\`json
{
"id": "123",
"email": "user@example.com",
"name": "John Doe",
"createdAt": "2024-01-01T00:00:00Z"
}
\`\`\`
### Errors
| Code | Description |
|------|-------------|
| 400 | Invalid request body |
| 409 | Email already exists |