08 - Professional Documentation with Claude

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.

Types of Documentation

A professional project requires different types of documentation, each with a specific purpose.

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

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.io

Complete README 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

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 docs

OpenAPI Example

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

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-up

Complete ADR Template

# 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-30

JSDoc and TSDoc Documentation

Inline documentation helps developers understand code without having to read the complete implementation.

Prompt for JSDoc

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 notes

Complete JSDoc Example

/**
 * 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: ${user.id}`);
   * } catch (error) {
   *   if (error instanceof ConflictError) {
   *     console.error('Email already registered');
   *   }
   * }
   * ```
   *
   * @see {@link UserService.update} to update an existing user
   * @since 1.0.0
   */
  async create(dto: CreateUserDto): Promise<User> {
    // Implementation...
  }

  /**
   * Retrieves a user by ID.
   *
   * @param id - User UUID
   * @returns The found user
   * @throws {NotFoundError} If user doesn't exist
   * @since 1.0.0
   */
  async findById(id: string): Promise<User> {
    // Implementation...
  }
}

Changelog

A well-structured changelog clearly communicates what changed between versions. Follow the "Keep a Changelog" format.

Prompt for Changelog

Generate a changelog entry for version 1.2.0.

CHANGES MADE:
1. Added email notification system for task deadlines
2. Added user preferences page
3. Fixed bug where tasks could be duplicated when clicking save twice
4. Fixed memory leak in websocket connections
5. Improved task filtering performance (50% faster)
6. Updated error messages for better UX
7. Removed deprecated v1 API endpoints

Follow Keep a Changelog format with sections:
- Added (new features)
- Changed (changes in existing functionality)
- Deprecated (features that will be removed)
- Removed (removed features)
- Fixed (bug fixes)
- Security (security fixes)

CHANGELOG.md Example

# Changelog

All notable changes to TaskFlow will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- Dark mode support (#234)
- Keyboard shortcuts for common actions

---

## [1.2.0] - 2025-02-01

### Added
- **Email notifications** for task deadlines
- **User preferences page** - Customize settings
- Export tasks to CSV format

### Changed
- Improved task filtering performance by 50%
- Updated error messages for better UX

### Fixed
- Fixed tasks duplicating when clicking save rapidly (#187)
- Fixed memory leak in websocket connections (#192)

### Removed
- Removed deprecated v1 API endpoints

---

## [1.1.0] - 2025-01-15

### Added
- Task labels and categories
- Bulk task operations

### Fixed
- Fixed sync issues across devices (#156)

### Security
- Updated dependencies to patch CVE-2025-1234

---

[Unreleased]: https://github.com/username/taskflow/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/username/taskflow/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/username/taskflow/releases/tag/v1.1.0

Documentation Best Practices

Documentation Checklist

Conclusion and Next Steps

Documentation is an investment that pays enormous dividends over time. It reduces onboarding time, decreases repetitive questions, and makes the project more professional and reliable.

Claude Code can generate a high-quality first draft, but content must be verified and customized. AI doesn't know the specific details of your project - you do.

In the next article we'll see how to use Claude Code for deploy and DevOps: multi-stage Dockerfiles, Docker Compose, CI/CD with GitHub Actions, health checks, and production logging.