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:
```typescript
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
MIT
API 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 |