Documentation and Knowledge Sharing

The Documentation Nobody Writes

In the previous lesson, we explored code review and refactoring. Now let’s build on that foundation. Ask any development team: “Is your documentation up to date?” Watch them laugh.

Documentation is the broccoli of software development—everyone knows it’s good for them, nobody wants to eat it. Code ships, features launch, docs… get added to next sprint’s backlog. Which rolls to the sprint after that. Which eventually gets marked as “won’t fix.”

AI changes this equation fundamentally. Not because it makes documentation exciting, but because it makes it nearly effortless. What used to take an afternoon now takes fifteen minutes.

The Five Types of Dev Documentation

Each type requires a different AI approach:

Doc Type	Purpose	AI Approach
API docs	How to use your endpoints	Generate from code + examples
Code comments	Why code does something	Generate, then edit for accuracy
README files	Project setup and overview	Generate from project structure
Architecture docs	How systems connect	Generate from code, verify with humans
Runbooks	How to operate and debug	Co-create with ops knowledge

Let’s work through each one.

API Documentation from Code

This is where AI documentation really shines. Here’s the workflow:

Step 1: Provide the endpoint code

Generate API documentation for this endpoint.
Include: description, parameters, request/response
examples, error codes, and authentication requirements.

Framework: Express.js with TypeScript
Auth: Bearer token (JWT)

[paste the endpoint code]
[paste the request/response types]

Step 2: AI generates structured docs

For an endpoint like:

router.post('/api/projects/:projectId/tasks',
  authMiddleware,
  validate(CreateTaskSchema),
  TaskController.create
);

AI produces:

## Create Task

Creates a new task within a project.

**Endpoint:** `POST /api/projects/:projectId/tasks`
**Authentication:** Required (Bearer token)

### Parameters

| Parameter | Type | Location | Required | Description |
|-----------|------|----------|----------|-------------|
| projectId | string (UUID) | path | yes | The project to add the task to |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| title | string | yes | Task title (1-200 chars) |
| description | string | no | Detailed description |
| assignee_id | string (UUID) | no | User to assign |
| priority | enum | no | low, medium, high, urgent |
| due_date | string (ISO 8601) | no | Task deadline |

### Example Request

POST /api/projects/550e8400-e29b-41d4-a716-446655440000/tasks
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "title": "Implement search feature",
  "priority": "high",
  "assignee_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

### Success Response (201)

{
  "id": "task_abc123",
  "title": "Implement search feature",
  "status": "open",
  "priority": "high",
  "created_at": "2026-02-05T10:30:00Z"
}

### Error Responses

| Status | Code | Description |
|--------|------|-------------|
| 400 | VALIDATION_ERROR | Invalid request body |
| 401 | UNAUTHORIZED | Missing or invalid token |
| 403 | FORBIDDEN | Not a project member |
| 404 | PROJECT_NOT_FOUND | Project doesn't exist |

This took AI about 10 seconds. Writing it manually would take 15-20 minutes per endpoint. For an API with 30 endpoints, you’re saving an entire day.

Explaining Legacy Code

Inherited a codebase with no documentation? This is AI’s time to shine.

Explain what this code does in plain English. Then create
a documentation comment for it. The audience is a mid-level
developer joining our team.

[paste the gnarly legacy function]

For a complex function, AI produces something like:

def reconcile_ledger(entries, cutoff_date, account_map):
    """
    Reconciles financial ledger entries against the account map.

    This function processes raw ledger entries and:
    1. Filters entries up to the cutoff date
    2. Groups entries by account code
    3. Validates each group against the expected account
       structure in account_map
    4. Identifies discrepancies (missing entries, balance
       mismatches, duplicate transactions)
    5. Returns a reconciliation report

    Args:
        entries: List of LedgerEntry objects from the database
        cutoff_date: Only process entries on or before this date
        account_map: Dict mapping account codes to expected
                     balances and validation rules

    Returns:
        ReconciliationReport with:
        - matched: entries that reconcile correctly
        - discrepancies: entries with issues
        - missing: expected entries not found
        - summary: overall reconciliation status

    Note: The nested loop at line 47 is intentional—it handles
    split transactions where a single ledger entry maps to
    multiple account codes.
    """

That last note is critical. AI can explain why code looks unusual, which is often more valuable than explaining what it does.

Quick Check: Documentation Smell Test

Read this AI-generated doc comment. What’s suspicious?

def get_users(status="active", limit=100):
    """
    Retrieves users filtered by status.

    Args:
        status: Filter by user status (active, inactive, pending)
        limit: Maximum number of users to return (default 100)

    Returns:
        List of User objects matching the criteria

    Raises:
        DatabaseError: If the database connection fails
    """

The suspicious part: does this function actually raise DatabaseError? Or did AI assume it would because database functions typically could? Always verify that documented behaviors match actual code behavior. AI sometimes documents what code should do rather than what it does.

README Generation

For new projects or repos that never got a proper README:

Generate a README.md for this project based on its structure.

Here's the directory tree:
[paste output of tree command]

Here's package.json (or requirements.txt, go.mod, etc.):
[paste dependency file]

Here's the main configuration file:
[paste config]

Include: project description, prerequisites, setup
instructions, running locally, running tests, deployment,
and project structure overview.

AI produces a comprehensive README that new team members can actually follow. The key is providing the real project files—AI will extract the correct setup commands, dependencies, and configuration from actual files rather than guessing.

Architecture Documentation

This requires a collaborative approach. AI can’t know your architecture from code alone—it needs your guidance on the “why.”

Help me document our system architecture. I'll describe
the high-level design and you'll create structured
documentation.

System: E-commerce order processing
Components:
- API Gateway (Express.js) - handles auth, rate limiting
- Order Service (Python) - business logic, validation
- Payment Service (Go) - Stripe integration
- Notification Service (Node.js) - email, SMS, push
- PostgreSQL - orders, users
- Redis - session cache, rate limiting
- RabbitMQ - async communication between services

Create architecture documentation including:
1. System overview diagram description
2. Component responsibilities
3. Communication patterns
4. Data flow for a typical order
5. Failure modes and how they're handled

AI creates the structure and prose. You verify the accuracy and add the context that only humans know—why certain decisions were made, what trade-offs were considered, what the future plans are.

Living Documentation: Keeping Docs Updated

The hardest part of documentation isn’t creating it—it’s keeping it current. Here are AI-powered strategies:

PR documentation checks:

Here's a PR diff. Does it change any behavior that should
be reflected in our API documentation?

[paste diff]
[paste current docs for affected endpoints]

Changelog generation:

Generate a changelog entry from these commits.
Write it from the user's perspective—what changed
for them, not internal implementation details.

[paste git log output]

Onboarding document updates:

Here's our current onboarding guide and a list of
changes we've made to the development environment
in the last quarter. What sections need updating?

[paste onboarding guide]
[paste list of environment changes]

Practical Exercise: Document Real Code

Pick one of these exercises (or do all three):

API docs: Take one endpoint from your project and generate complete API documentation using AI. Compare it to any existing docs.
Legacy explanation: Find the most confusing function in your codebase. Have AI explain it and generate a documentation comment.
README audit: Have AI review your project’s README against the actual project structure. Ask it what’s missing or outdated.

Each exercise should take 5-10 minutes and save you hours of future documentation work.

Key Takeaways

AI makes documentation nearly effortless—15 minutes instead of an afternoon
Provide actual code for accurate API docs, not descriptions of code
Verify AI-generated docs against real behavior—AI sometimes documents idealized behavior
Use AI to explain legacy code for onboarding and knowledge transfer
Build documentation into your PR workflow so docs stay current
Architecture docs require collaboration—AI structures, you verify

Next up: architecture decisions. When you’re faced with “should we use microservices or a monolith?” and “which database fits our use case?"—AI can help you reason through the trade-offs.

Up next: In the next lesson, we’ll dive into Architecture Decisions and System Design.