Diátaxis Framework
| Mode | Purpose | Reader Asks | Form |
|---|
| Tutorial | Learning-oriented | 'How do I get started?' | Step-by-step lesson |
| How-To Guide | Task-oriented | 'How do I solve X?' | Steps to complete a task |
| Reference | Information-oriented | 'What does X do?' | Technical descriptions, API docs |
| Explanation | Understanding-oriented | 'Why is it designed this way?' | Background, context, decisions |
README Structure
| Item | Description |
|---|
1. Title + Badge | Project name + build/pypi/npm/coverage badges — credibility signals |
2. One-Liner | One sentence that describes what it does and why it exists |
3. Screenshot/Demo | Show, don't tell. GIF or image of working product |
4. Quick Start | 5-minute setup: clone → install → run → see result. Copy-paste commands. |
5. Features | Bullet list of key capabilities. Not exhaustive, highlights. |
6. Documentation Link | Link to full docs site. README is a gateway, not the whole manual. |
7. Contributing | How to set up dev environment, run tests, submit PRs |
API Documentation
| Item | Description |
|---|
Overview | What the API does, authentication method, base URL, rate limits |
Endpoints | Method, path, description, parameters (required/optional/types), request/response examples |
Authentication | API keys, OAuth flow, how to get credentials, token format |
Error Codes | List of error codes with descriptions and troubleshooting guidance |
Code Examples | cURL, Python, JavaScript, Go — at minimum. Copy-paste ready. |
SDK Documentation | If SDK exists: installation, instantiation, key methods with examples |
Maintenance
| Item | Description |
|---|
Doc-as-Code | Docs in same repo as code. PR reviews include doc updates. Docs versioned with releases. |
'Docs or It Didn't Happen' | Every feature requires doc PR before merge. Part of definition of done. |
Regular Audits | Quarterly: walk through docs as a new user. Fix broken links, outdated screenshots, stale info. |
Doc Analytics | Track page views, search queries, bounce rate. Fix pages with high bounce / low time on page. |
Pro Tip: The Diátaxis framework: separate documentation into 4 modes — Tutorials (learning), How-To Guides (tasks), Reference (technical), Explanation (understanding). Each has a distinct reader and purpose.