Automating Documentation Updates - Maintaining READMEs and Comments

Introduction

"I wrote the code, but forgot to update the documentation."

This is a challenge development teams face every day. When code and documentation diverge, onboarding new members becomes painful, and implementations based on outdated information become a breeding ground for bugs.

Why doesn't documentation get updated? The reason is simple: documentation updates are treated as an afterthought. Feature implementations and bug fixes take priority, documentation gets pushed to "later," and that "later" never comes.

DevLoop Runner solves this problem structurally. A dedicated documentation phase is built into Dev Run's 10-phase workflow, so documentation is automatically updated alongside code changes. The option to "forget" simply doesn't exist.

This article covers the concept of documentation debt, how Dev Run's documentation phase works, a guide for different documentation types, and quality checkpoints for review.

What Is Documentation Debt?

Like technical debt, "documentation debt" is a hidden cost that threatens project health.

How Documentation Debt Accumulates

Loading diagram...

The Cost of Documentation Debt

Impact	Example
Onboarding delays	New members waste time following outdated docs
Bug introduction	Developers implement based on stale API specs
Increased inquiries	Docs don't help, so direct questions multiply
Trust erosion	A culture of "don't trust the docs" takes hold

With DevLoop Runner, documentation is automatically updated with every code change, preventing this debt from accumulating.

Dev Run's Documentation Phase: Kohaku's Role

In Dev Run's 10 phases, Phase 8 "Documentation" is handled by Kohaku, the Tech Writer persona.

What Kohaku Does in the Documentation Phase

1. Understands the changes: Analyzes files and content modified during the implementation phase
2. Identifies affected documentation: README, API docs, code comments, and more
3. Creates or updates documentation: Generates documentation reflecting the changes
4. Verifies consistency: Checks that documentation content matches the code

Why a Dedicated Persona Matters

When documentation is left to the implementer (Riku), several problems tend to arise:

• Explanations lean too heavily on implementation details, lacking the user's perspective
• Things the author "already knows" get omitted
• Documentation priority drops, and quality suffers

Kohaku, as a documentation-dedicated persona, focuses on the user's perspective. Rather than documenting internal structures, Kohaku centers on "how to use it" and "what changed."

Where the Documentation Phase Sits

Loading diagram...

It's placed after implementation and testing because documentation should reflect the final state of the code. Since implementation doesn't change after testing, the consistency between documentation and code is guaranteed.

Documentation Type Guide

1. README Updates

The README is your project's "front door." When features are added or configurations change, it's the documentation that most needs updating.

Auto-updated by Dev Run:

When Dev Run implements a new feature, Kohaku automatically updates README sections like setup instructions and feature lists.

When to create a dedicated Issue:

For comprehensive README improvements, create a focused Issue.

## Overview
Comprehensively improve the "Setup" section of README.md.

## Current Problems
- Node.js version requirement is outdated (says 16, actually needs 18+)
- No pnpm instructions
- Incomplete environment variable list
- No Windows setup instructions

## Improvements
1. Update prerequisites (Node.js 18+, pnpm 8+)
2. OS-specific setup instructions (macOS / Windows / Linux)
3. Complete environment variable list with descriptions
4. Add common errors and solutions section

## Reference Files
- .env.example
- package.json
- docker-compose.yml

2. API Documentation

API documentation is a contract with external consumers. Inaccurate API docs cause significant confusion for developers building integrations.

Example Issue:

## Overview
Generate OpenAPI (Swagger) format documentation for the REST API endpoints
under src/api/.

## Target Endpoints
- POST /api/users (create user)
- GET /api/users/:id (get user)
- PUT /api/users/:id (update user)
- DELETE /api/users/:id (delete user)

## Output Requirements
- Output to docs/api/openapi.yaml
- Description for each endpoint
- Request body schema definitions
- Response schema definitions (success/error)
- Authentication method documentation (Bearer Token)
- Request/response examples for each endpoint

## Reference Files
- src/api/routes/users.ts
- src/types/user.ts
- src/middleware/auth.ts

Tip: For API docs, it's important to specify both schema definitions and concrete request/response examples. Schemas alone make it hard for consumers to understand actual usage.

3. Code Comments (JSDoc / TSDoc)

Code comments are documentation written for developers who read the code.

Example Issue:

## Overview
Add JSDoc comments to src/services/paymentProcessor.ts.

## Requirements
- Add JSDoc to all public functions
- Parameter types and descriptions
- Return type and description
- Conditions under which exceptions are thrown
- Usage examples with @example
- Add inline comments for complex business logic

## Expected Format
/**
 * Process a payment and return the result
 * @param orderId - The order ID
 * @param amount - Payment amount in cents
 * @param method - Payment method
 * @returns Payment result object
 * @throws PaymentError - When payment processing fails
 * @example
 * const result = await processPayment('order-123', 1000, 'credit');
 */

## Reference
Match the comment style of existing src/services/userService.ts

4. CHANGELOG

The CHANGELOG records release history. It's a critical document for users and operations teams to understand "what changed."

Example Issue:

## Overview
Add v2.1.0 release notes to CHANGELOG.md.

## Format
Follow Keep a Changelog conventions

## Changes

### Added
- Dark mode support (#123)
- Multi-language support: Japanese / English (#145)
- CSV export feature (#167)

### Changed
- Dashboard layout redesign (#134)
- Unified API response date format to ISO 8601 (#156)

### Fixed
- CSRF token validation error during login (#178)
- Search results pagination not working correctly (#182)

### Deprecated
- /api/v1/users endpoint (to be removed in v3.0.0)

## Notes
- Include links to Issue numbers
- Use YYYY-MM-DD date format

Benefits of Automatic Documentation Updates

Dev Run's documentation phase provides several key advantages.

1. Code and Documentation Stay in Sync

In Dev Run, documentation updates are included in the same PR as code changes. This means code and documentation are always reviewed and merged at the same time, preventing divergence.

2. Reduced Review Burden

When documentation is written manually, reviewers must verify that "documentation content matches the code." With Dev Run, Kohaku generates documentation after analyzing code changes, resulting in high consistency and lighter review loads.

3. Consistent Documentation Style

When multiple developers write documentation, styles vary. Kohaku generates documentation to the same standard every time, unifying documentation style across the project.

4. Faster New Member Onboarding

When documentation is always current, new members can trust the docs and learn confidently. No more asking "Is this documentation up to date?"

Documentation Quality Checkpoints

Use this checklist when reviewing documentation generated by Dev Run.

Accuracy

• Does it match the code's actual behavior?
• Are API parameters and return values correct?
• Are version numbers and configuration values accurate?
• Are code examples executable?

Completeness

• Are all changed areas reflected in the documentation?
• Are prerequisites and dependencies documented?
• Are error cases and troubleshooting included?

Readability

• Are technical terms properly explained?
• Are step-by-step instructions logical?
• Are diagrams and code examples used effectively?
• Is the detail level appropriate for the target audience?

Maintainability

• Are there no hardcoded values (URLs, version numbers)?
• Is duplication with other documentation minimized?
• Are there descriptions that will break easily with future changes?

Best Practices for Documentation-Only Issues

Beyond Dev Run's automatic updates, there are cases where dedicated documentation Issues are valuable.

Combining with Code Changes

Include documentation requirements in feature implementation Issues.

## Implementation
- Implement user invitation feature

## Documentation Requirements
- Add invitation feature overview to README
- Create new docs/features/invitation.md
- Add POST /api/invitations to API documentation

In this case, Dev Run's implementation phase builds the feature, and the documentation phase has Kohaku create and update the docs.

Improving Existing Documentation

Issues focused solely on documentation improvement are also effective.

## Overview
Improve the "Deployment" section of the developer guide

## Current Problems
- No Docker-based deployment instructions
- No distinction between production and development environments
- No rollback procedure documented

## Improvements
1. Add Docker Compose deployment instructions
2. Explain environment-specific configuration files
3. Pre-deployment checklist
4. Rollback procedure
5. Troubleshooting section

## Reference Files
- docker-compose.yml
- docker-compose.prod.yml
- .env.example
- .env.production.example

Detecting Documentation Debt with Create Issue

DevLoop Runner's Create Issue feature can detect not just code technical debt, but documentation debt as well.

Examples of detected documentation debt:

• README references to files that no longer exist
• Code comments that contradict the actual logic
• API endpoints not documented in API docs
• Changes not recorded in the CHANGELOG

We recommend running Create Issue regularly and checking for documentation debt alongside technical debt.

Summary

• Documentation debt is as costly as technical debt: Left unchecked, it causes onboarding delays, bug introduction, and trust erosion
• Dev Run's documentation phase: Kohaku automatically updates documentation based on code changes -- the "forgetting" problem is structurally eliminated
• Write Issues by documentation type: README, API docs, code comments, and CHANGELOG each have their own best practices
• Code and docs in the same PR: With Dev Run, they're reviewed and merged together, preventing divergence
• Don't skip quality checks: Review for accuracy, completeness, readability, and maintainability
• Detect documentation debt with Create Issue: Regular scans prevent debt accumulation

Documentation isn't something you "write and forget" -- it's something you "maintain continuously." By letting DevLoop Runner's Kohaku handle documentation updates, you can keep your docs current and trustworthy at all times.