- Why Developers Must Write Documentation
- Good README vs. Bad README
- Usage Example
- Architecture
- Contributing
- License
- Architecture Decision Records (ADR)
- The Diátaxis Framework: 4 Types of Documentation
- Step 2: Create app.py
- Step 3: Run It
- Verify
- Documentation Tools: Docusaurus, GitBook, Mintlify
- Common Documentation Anti-patterns
- Practical Checklist
- Conclusion
- References
Why Developers Must Write Documentation
You've probably heard the saying: "The code is the documentation." Well, it's half right and half wrong. Code shows what happens, but never explains why or how to use it.
Great technical documentation:
- Shortens onboarding - New team members become productive in days, not weeks
- Reduces bugs - Clear API documentation prevents misuse
- Lowers maintenance costs - You'll understand your own code 6 months later
- Builds trust - Well-documented projects feel professional and reliable
Major tech companies like Google, Meta, and Amazon include "documentation writing ability" in engineer evaluations. Documentation is no longer optional—it's essential.
Good README vs. Bad README
The Bad README
# Project X
This is a project.
## Usage
```bash
npm install
npm start
```
Done!
Problems with this README:
- **What do I do after installing?** Unclear
- **What problem does it solve?** Unknown
- **What technologies are used?** No clue
- **Who can use this?** Not specified
### The Good README Structure
```markdown
# Project Name
**One-liner**: The specific problem this project solves
## Key Features
- Feature 1
- Feature 2
- Feature 3
## Quick Start
### Prerequisites
- Node.js 18.0+
- npm 9.0+
### Installation & Running
```bash
git clone https://github.com/user/project.git
cd project
npm install
npm run dev
Usage Example
const project = new Project()
project.doSomething()
Architecture
[ASCII diagram or image]
Contributing
License
README Checklist:
- [ ] Project goal is clear in the first 3 lines?
- [ ] At least one usage example included?
- [ ] Prerequisites explicitly stated?
- [ ] Architecture diagram or visual included?
- [ ] Contributing guidelines clear?
- [ ] Troubleshooting section present?
## API Documentation: OpenAPI and Swagger
API documentation shouldn't be plain text—it should be **machine-readable**. Using the OpenAPI standard (formerly Swagger) enables:
1. **Documentation stays in sync with code** - Changes are automatically reflected
2. **Auto-generate client code** - SDKs for JavaScript, Python, Go, etc.
3. **Interactive testing** - Try endpoints directly in the browser
### OpenAPI 3.0 Basic Structure
```yaml
openapi: 3.0.0
info:
title: User Management API
version: 1.0.0
description: API for managing user information
servers:
- url: https://api.example.com/v1
description: Production
paths:
/users:
get:
summary: Retrieve all users
parameters:
- name: limit
in: query
schema:
type: integer
description: Maximum number of users to return
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
post:
summary: Create a new user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
email:
type: string
format: email
required:
- id
- name
- email
OpenAPI Validation Tools
- Swagger UI: Interactive browser-based API testing interface
- ReDoc: Beautiful auto-generated documentation
- OpenAPI Linter: Validates specification consistency
Architecture Decision Records (ADR)
An ADR documents an architectural choice and the reasoning behind it. Whether migrating to microservices or adopting a new library, recording these decisions is crucial.
ADR Template
# ADR-001: Migrate Frontend to React
## Status
Approved
## Context
Legacy jQuery codebase is difficult to maintain. New developers struggle with it.
We need a modern framework.
## Options
1. **React**: Large community, extensive libraries, easy hiring
2. **Vue**: Low learning curve, excellent documentation
3. **Angular**: Full framework, good for large projects
## Decision
**Choose React**
## Rationale
- Team experience: Some members already know React
- Hiring: React developers are plentiful in the market
- Ecosystem: Next.js, TanStack Query, and other excellent tools
- Community: Easy to find answers on Stack Overflow and GitHub
## Trade-offs
- Larger bundle size than Vue
- Steeper learning curve than Vue
- Requires additional state management library (Redux, Zustand, etc.)
## Consequences (6 months later)
Development productivity increased by 40%. New developer onboarding time reduced by 2 weeks.
ADR Benefits:
- Preserves decision history - Know why a technology was chosen months later
- Triggers re-evaluation - When circumstances change, you can review the ADR
- Eases onboarding - "Why React?" gets answered immediately
The Diátaxis Framework: 4 Types of Documentation
The biggest confusion in technical writing is: What kind of documentation do I need? The Diátaxis framework categorizes documentation into 4 clear types:
| Type | Audience | Goal | Characteristics |
|---|---|---|---|
| Tutorial | Beginners | Learn | Step-by-step, all steps included, guaranteed results |
| How-to Guide | Experienced users | Complete a task | Problem-specific, standalone |
| Reference | Developers | Find information | Structured, searchable, comprehensive |
| Explanation | Students | Understand | Background knowledge, reasoning |
Tutorial: Step-by-Step for Complete Beginners
# Tutorial: Build Your First Web API
In this tutorial, you'll create a working web API in 15 minutes.
## What You Need
- Python 3.9+
- Terminal
## Step 1: Install Flask
```bash
pip install flask
```
Step 2: Create app.py
from flask import Flask
app = Flask(__name__)
@app.route('/api/hello', methods=['GET'])
def hello():
return {'message': 'Hello, World!'}
if __name__ == '__main__':
app.run(debug=True)
Step 3: Run It
python app.py
Verify
Open http://localhost:5000/api/hello in your browser
### How-to Guide: Problem-Solving for Experienced Users
```markdown
# How-to: Fix CORS Errors
When your frontend gets a CORS error calling your API:
```python
from flask_cors import CORS
app = Flask(__name__)
CORS(app) # Allow all domains
Or for specific domains:
CORS(app, origins=['https://example.com'])
### Reference: Complete API Reference
```markdown
# API Reference
## GET /api/users/{id}
Retrieve user information.
**Parameters:**
- `id` (integer, required): User ID
**Response:**
```json
{
"id": 1,
"name": "John Doe",
"email": "john@example.com"
}
Errors:
- 404: User not found
### Explanation: The Reasoning Behind the Design
```markdown
# Explanation: Why Microservices Architecture?
Microservices break one large application into small, independent services.
This increases team velocity, scalability, and flexibility.
However, complexity also increases...
Documentation Tools: Docusaurus, GitBook, Mintlify
Docusaurus (Open Source, React-Based)
npx create-docusaurus@latest my-docs classic
cd my-docs
npm run start
Advantages:
- Full React and MDX support
- Builds to static site for easy deployment
- Built-in versioning
GitBook (Cloud-Based)
- Excellent collaboration features
- Beautiful default design
- May require payment
Mintlify (API Documentation Focused)
- OpenAPI integration
- Terminal-like code blocks
- Modern design
Common Documentation Anti-patterns
1. "We Don't Have Time for Documentation"
Reality: 5 hours of documentation today saves 50 hours tomorrow.
2. Thinking Code Comments Are Documentation
Comments explain the "what." Documentation explains the "why" and shows the big picture.
3. Storing Documentation Separately from Code
Solution: Keep docs in the repository and review them with code PRs.
docs/
├── README.md
├── api/
│ ├── users.md
│ └── posts.md
├── architecture/
│ └── decisions/
│ ├── 001-react-migration.md
│ └── 002-microservices.md
└── guides/
├── setup.md
└── contributing.md
4. Putting Everything in One Document
Better structure:
- README: Project overview (1-2 minutes)
- CONTRIBUTING: How to contribute (link)
- docs/SETUP: Development setup (10 minutes)
- docs/ARCHITECTURE: System design (30 minutes)
- API_REFERENCE: Specs (auto-generated)
Practical Checklist
Before publishing any documentation:
- Is the title clear? "API docs" is weaker than "User Management API Reference"
- Is the audience defined? Who reads this document?
- Is it executable? Do the steps actually work?
- Are examples included? Concrete examples beat abstract descriptions
- Are screenshots/diagrams included? Visuals are worth 1000 words
- Is it current? Specify the version if outdated
- Is it searchable? Include relevant keywords
- Do all links work? Especially external links
- Is there an owner? Who maintains this?
Conclusion
Technical documentation is an investment, not a cost. Good documentation:
- Accelerates team velocity
- Reduces bugs
- Shortens new developer onboarding
- Becomes evidence of your expertise
This week, review your README. Write one ADR. Your future self will thank you.