Professional Documentation with Claude Code
Documentation is often the most neglected aspect of software development, yet it is fundamental for maintainability and onboarding new developers. Well-written documentation can save hours of debugging and confusion. With Claude Code, writing professional documentation becomes fast and systematic.
In this article we'll explore how to use Claude Code to create professional READMEs, API documentation with OpenAPI, Architecture Decision Records, comprehensive JSDoc/TSDoc, and well-structured changelogs.
Series Overview
| # | Article | Focus |
|---|---|---|
| 1 | Foundation and Mindset | Setup and mindset |
| 2 | Ideation and Requirements | From idea to MVP |
| 3 | Backend Architecture | API and database |
| 4 | Frontend Structure | UI and components |
| 5 | Context and Setup | CLAUDE.md and project context |
| 6 | Prompt Engineering | Advanced prompts and agents |
| 7 | Testing and Quality | Unit, integration, E2E |
| 8 | You are here - Documentation | README, API docs, ADR |
| 9 | Deploy and DevOps | Docker, CI/CD |
| 10 | Evolution | Scalability and maintenance |
Types of Documentation
A professional project requires different types of documentation, each with a specific purpose.
Documentation Map
| Type | Audience | Purpose | Update Frequency |
|---|---|---|---|
| README.md | Everyone | First impression, quick start | Every major release |
| API Docs | API Developers | Endpoint reference | Every API change |
| ADR | Technical team | Architectural decisions | Per decision |
| JSDoc/TSDoc | Developers | Code reference | With the code |
| CHANGELOG | Users/Dev | Change history | Every release |
| CONTRIBUTING | Contributors | How to contribute | Rarely |
| Runbook | Operations | Operational procedures | When they change |
Professional README
The README is the first thing a visitor sees. It should quickly communicate what the project does, how to use it, and how to contribute.
Prompt for Complete README
Prompt - Generate Professional README
Create a professional README.md for my project:
PROJECT INFO:
- Name: TaskFlow
- Type: SaaS task management for freelancers
- Stack: Node.js 20, Express 5, TypeScript 5.3, PostgreSQL 16, Angular 17
- Status: Beta (production-ready)
- License: MIT
FEATURES:
1. Project and task management with drag-and-drop
2. Time tracking with automatic reminders
3. Invoice generation from tracked time
4. Team collaboration (up to 5 users)
5. Integrations: Slack, Google Calendar, Stripe
SECTIONS TO INCLUDE:
1. Project title with logo placeholder and badges
2. One-paragraph description (compelling, benefit-focused)
3. Screenshots/demo section
4. Key features list with icons
5. Tech stack with version badges
6. Prerequisites
7. Installation (step-by-step, copy-pasteable)
8. Configuration (environment variables table)
9. Usage examples with code
10. API documentation link
11. Testing instructions
12. Deployment guide
13. Contributing guidelines
14. Roadmap (future features)
15. License
16. Contact/support info
STYLE:
- Use emojis sparingly for visual hierarchy
- Include copy-paste ready commands
- Add collapsible sections for detailed content
- Include badges from shields.ioComplete README Template
README.md - Professional Template
# TaskFlow
<p align="center">
<img src="docs/images/logo.png" alt="TaskFlow Logo" width="200">
</p>
<p align="center">
<strong>The smart task management platform for freelancers</strong>
</p>
<p align="center">
<a href="#features">Features</a> |
<a href="#quick-start">Quick Start</a> |
<a href="#documentation">Documentation</a> |
<a href="#contributing">Contributing</a>
</p>
<p align="center">
<img src="https://img.shields.io/badge/version-1.0.0-blue" alt="Version">
<img src="https://img.shields.io/badge/license-MIT-green" alt="License">
<img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build">
<img src="https://img.shields.io/badge/coverage-87%25-yellow" alt="Coverage">
</p>
---
## Overview
TaskFlow helps freelancers and small teams manage projects, track time,
and generate invoices - all in one place. Stop juggling multiple tools
and focus on what matters: delivering great work.
## Features
| Feature | Description |
|---------|-------------|
| **Task Management** | Kanban boards, lists, and calendar views |
| **Time Tracking** | One-click timer with automatic reminders |
| **Invoicing** | Generate professional invoices from tracked time |
| **Team Collaboration** | Real-time sync for teams up to 5 members |
| **Integrations** | Slack, Google Calendar, Stripe |
## Quick Start
### Prerequisites
- Node.js >= 20
- PostgreSQL >= 15
- Redis >= 7
### Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/taskflow.git
cd taskflow
# Install dependencies
npm install
# Copy environment file
cp .env.example .env
# Run database migrations
npm run db:migrate
# Start development server
npm run dev
```
## Configuration
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `DATABASE_URL` | PostgreSQL connection string | Yes | - |
| `JWT_SECRET` | Secret for JWT signing | Yes | - |
| `REDIS_URL` | Redis connection string | Yes | - |
## Testing
```bash
npm test # Run all tests
npm run test:coverage # With coverage report
npm run test:e2e # E2E tests
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
MIT License - see [LICENSE](LICENSE) for details.API Documentation with OpenAPI
API documentation should be auto-generated from code when possible, but Claude Code can help write initial OpenAPI specifications or enrich them.
Prompt for OpenAPI Spec
Prompt - Generate OpenAPI Specification
Generate OpenAPI 3.1 specification for these endpoints:
RESOURCE: Tasks
BASE PATH: /api/v1/tasks
ENDPOINTS:
1. POST /tasks - Create task
2. GET /tasks - List tasks (paginated, filterable)
3. GET /tasks/:id - Get task by ID
4. PATCH /tasks/:id - Update task
5. DELETE /tasks/:id - Delete task
TASK SCHEMA:
- id: UUID (readonly)
- title: string (required, 3-200 chars)
- description: string (optional, max 5000)
- status: enum [todo, in_progress, done]
- priority: enum [low, medium, high]
- dueDate: ISO8601 datetime (optional)
- projectId: UUID (required)
- createdAt: datetime (readonly)
- updatedAt: datetime (readonly)
INCLUDE:
- Complete request/response schemas
- All query parameters for list endpoint
- Authentication (Bearer token)
- Error responses (400, 401, 403, 404, 500)
- Example values for all fields
- Descriptions for public docsOpenAPI Example
YAML - openapi.yaml (Tasks Resource)
openapi: 3.1.0
info:
title: TaskFlow API
description: API for task and project management.
version: 1.0.0
servers:
- url: https://api.taskflow.dev/v1
description: Production
- url: http://localhost:3000/api/v1
description: Local Development
paths:
/tasks:
post:
tags: [Tasks]
summary: Create a new task
operationId: createTask
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTaskRequest'
responses:
'201':
description: Task created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TaskResponse'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/Unauthorized'
get:
tags: [Tasks]
summary: List tasks
operationId: listTasks
security:
- bearerAuth: []
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: limit
in: query
schema:
type: integer
default: 20
- name: status
in: query
schema:
type: string
enum: [todo, in_progress, done]
responses:
'200':
description: Task list
content:
application/json:
schema:
$ref: '#/components/schemas/TaskListResponse'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
CreateTaskRequest:
type: object
required: [title, projectId]
properties:
title:
type: string
minLength: 3
maxLength: 200
description:
type: string
maxLength: 5000
projectId:
type: string
format: uuid
priority:
type: string
enum: [low, medium, high]
default: medium
TaskResponse:
type: object
properties:
data:
$ref: '#/components/schemas/Task'
responses:
ValidationError:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Not authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/Error'Architecture Decision Records (ADR)
ADRs document important architectural decisions, the context in which they were made, and the alternatives considered. They are fundamental to understanding the "why" behind technical choices.
Prompt for ADR
Prompt - Generate ADR
Create an Architecture Decision Record (ADR) for this decision:
DECISION: Use PostgreSQL as database instead of MongoDB
CONTEXT: We're building a task management SaaS
DATE: 2025-01-30
FACTORS CONSIDERED:
1. Strongly relational data (users, projects, tasks, time entries)
2. Need for complex queries and reporting
3. ACID compliance for financial data (invoicing)
4. Team familiarity with SQL
5. Future scaling needs
ALTERNATIVES:
1. MongoDB - NoSQL, flexible schema
2. MySQL - Traditional RDBMS
3. CockroachDB - Distributed SQL
Follow the standard ADR template with:
- Title (ADR-XXX: Brief description)
- Status
- Context
- Decision
- Alternatives Considered (with pros/cons)
- Consequences (positive, negative, risks)
- Notes/Follow-upComplete ADR Template
docs/adr/ADR-001-database-postgresql.md
# ADR-001: PostgreSQL as Primary Database
## Status
**Accepted** - 2025-01-30
## Context
We're designing the backend for TaskFlow, a SaaS platform for task management.
The system must handle:
- **Users and teams:** N:M relationships with roles
- **Projects and tasks:** Hierarchical structure
- **Time tracking:** Work sessions with timestamps
- **Billing:** Financial data requiring precision
### Key Requirements
1. **Data integrity:** Financial data requires ACID transactions
2. **Complex queries:** Reports aggregating multiple tables
3. **Scalability:** MVP 1000 users, target 50,000 in 18 months
## Decision
We use **PostgreSQL 16** as primary database with **Prisma ORM**.
### Rationale
1. **Relational model:** Our data is strongly relational
2. **ACID compliance:** Atomic transactions for financial operations
3. **Powerful queries:** JOINs, aggregations, window functions
4. **JSONB:** Flexibility for metadata without sacrificing structure
5. **Maturity:** Excellent documentation, active community
## Alternatives Considered
### MongoDB
| Aspect | Pro | Con |
|--------|-----|-----|
| Schema | Flexible | Less integrity |
| Query | Simple documents | Expensive JOINs |
**Decision:** Rejected. Our data is relational.
### MySQL 8
| Aspect | Pro | Con |
|--------|-----|-----|
| Familiarity | Widespread | Less JSON support |
**Decision:** Valid, but PostgreSQL offers more advanced features.
## Consequences
### Positive
1. Powerful queries for analytics
2. Guaranteed integrity
3. Excellent ecosystem
### Negative
1. Horizontal scaling requires more work
2. Schema migrations required
## Follow-up Actions
- [ ] Setup Prisma with PostgreSQL
- [ ] Configure docker-compose for development
- [ ] Define initial schema
---
**Author:** Team Lead
**Last Updated:** 2025-01-30JSDoc and TSDoc Documentation
Inline documentation helps developers understand code without having to read the complete implementation.
Prompt for JSDoc
Prompt - Add JSDoc Documentation
Add comprehensive JSDoc documentation to this TypeScript code:
```typescript
[PASTE CODE HERE]
```
INCLUDE FOR EACH FUNCTION/METHOD:
1. Brief description (one sentence)
2. Detailed explanation (if complex)
3. @param for each parameter with type and description
4. @returns with type and description
5. @throws for each exception that can be thrown
6. @example with realistic usage
7. @see for related functions
8. @since version number
9. @deprecated if applicable
STYLE:
- Use imperative mood ("Creates a user" not "This creates a user")
- Document edge cases in description
- Include validation rules in @param descriptions
- Add @remarks for implementation notesComplete JSDoc Example
TypeScript - Documented Service
/**
* Service for user management.
*
* Handles CRUD operations, authentication and authorization for users.
* All passwords are hashed with bcrypt before saving.
*
* @remarks
* This service doesn't directly handle JWT tokens. See {@link AuthService}
* for authentication operations.
*
* @example
* ```typescript
* const userService = new UserService(userRepository, emailService);
*
* // Create a new user
* const user = await userService.create({
* name: 'John Doe',
* email: 'john@example.com',
* password: 'SecurePass123!'
* });
* ```
*
* @since 1.0.0
*/
export class UserService {
/**
* Creates a new UserService instance.
*
* @param userRepository - Repository for user data access
* @param emailService - Service for sending emails
*/
constructor(
private readonly userRepository: UserRepository,
private readonly emailService: EmailService
) {}
/**
* Creates a new user in the system.
*
* Validates input data, checks that email is not already registered,
* hashes password and sends welcome email.
*
* @param dto - User creation data
* @param dto.name - Full name (2-100 characters)
* @param dto.email - Valid and unique email
* @param dto.password - Password (min 8 char, 1 uppercase, 1 number)
*
* @returns The created user (without password)
*
* @throws {ValidationError} If data doesn't pass validation
* @throws {ConflictError} If email is already registered
*
* @example
* ```typescript
* try {
* const user = await userService.create({
* name: 'John Doe',
* email: 'john@example.com',
* password: 'SecurePass123!'
* });
* console.log(`User created: