Part 1: Why Automate Code Documentation

Undocumented code is technical debt with a compounding interest rate.

Every function without a docstring costs time when the next engineer, or the same engineer six months later, tries to understand what it does. Every class without inline comments requires archaeology instead of engineering. Every module without a README creates onboarding friction that scales with team size.

The research on what poor documentation costs is consistent: developers spend 19% of their working time understanding existing code, according to a McKinsey study of software productivity. In an 8-hour day, that is 91 minutes spent reading code that should have been documented when it was written.

The reason it was not documented when it was written is simple: documentation is the task engineers complete last, after the problem is solved, when cognitive energy is depleted and the deadline pressure has already been released. It is not laziness. It is human nature. The work feels done when the tests pass.

AI changes the economics of documentation entirely. What previously required 30 minutes of careful writing per function, performed by the engineer who wrote it while their attention was elsewhere, now requires 30 seconds of AI generation and 2 minutes of human review. The quality is high because AI has access to the full function body, the calling context, and patterns from millions of documented functions in its training data.

What documented code actually produces:

A Google study of developer productivity found that teams with high code documentation quality onboarded new engineers 35% faster. New engineers reached full productivity in 6 weeks instead of 9 weeks. For a team hiring 4 engineers per year at a fully-loaded cost of $200,000 each, faster onboarding means each engineer is productive for 3 additional weeks. Annual value of the documentation improvement: $46,000 in recovered productivity, before accounting for the reduction in interruptions to senior engineers answering questions that documentation would have answered.

Beyond onboarding, documented code reduces the cost of debugging, code review, and refactoring. Engineers reviewing a pull request for a well-documented function spend 40% less time on the review, according to internal studies at multiple software companies. The time savings compound across every review, every debugging session, every refactor.

The 11-week adoption insight:

This article is the second in the Engineering & DevOps AI series. The first covered AI PR review, which delivers the fastest measurable result: 26% more pull requests merged weekly.

Code documentation automation is the right second deployment because it builds trust in AI output at low risk. Documentation is read-only: AI generates a docstring, a human reads it, the human decides whether to keep it. No merge, no deployment, no production risk. Engineers who are skeptical of AI coding tools, the 71% who say they do not fully trust AI output in 2026, encounter AI documentation in its most auditable form: a human-readable description of what the code does, verifiable against the code itself.

Teams that deploy documentation automation alongside PR review hit the 11-week productivity inflection point faster because engineers are interacting with AI output daily in a low-stakes context, building the pattern recognition that transfers to higher-stakes AI uses.

The scope of the problem in most codebases:

Run this command in any mature codebase and see what you find:

grep -r "def " src/ | wc -l    # Total Python functions
grep -r '"""' src/ | wc -l     # Functions with docstrings

In most production codebases more than 3 years old, fewer than 30% of functions have documentation. In codebases with high engineer turnover, the number is often below 15%. The AI documentation automation runs against the entire codebase, identifies every undocumented function, generates documentation for each, and submits the results as pull requests for human review.

Part 2: How to Build the Code Documentation Pipeline

This pipeline runs on a schedule, scans your repository for undocumented functions and classes, generates documentation for each, and submits a pull request with all documentation additions for engineering review.

The pipeline:

Scheduled trigger (weekly, or on-demand)
→ Repository cloned to runner
→ Code parser scans all files for undocumented functions/classes
→ Each undocumented item sent to Claude API with full function context
→ Claude generates: docstring, parameter descriptions, return value, example usage
→ Documentation inserted into source files
→ Pull request opened against main branch
→ PR labeled "ai-documentation" for easy filtering
→ Slack notification to engineering lead

What Claude generates for each function:

For a Python function, Claude generates a Google-style or NumPy-style docstring (your choice) including a one-sentence summary of what the function does, a description of each parameter with type and purpose, the return value with type and description, any exceptions raised, and a brief usage example. For JavaScript and TypeScript, Claude generates JSDoc comments. For Go, Claude generates standard Go doc comments. For Java, Claude generates Javadoc.

The documentation is generated from the full function body, the calling context in the surrounding file, and the function signature. Claude does not guess at intent based on the function name alone. It reads what the code actually does.

Tools required:

ToolPurposeCost
GitHub ActionsScheduling and PR creationFree
Anthropic Claude APIDocumentation generation~$0.002 per function
Python / Node.jsCode parsingFree
GitHub APIPR creationFree

Total monthly cost for a codebase with 500 undocumented functions:

First run: approximately $1.00 in API costs. Ongoing (new functions each week): approximately $0.10-$0.50/week.

Step 1: Create the GitHub Actions Workflow

Create `.github/workflows/ai-documentation.yml` in your repository. The workflow runs on a weekly schedule (Sunday at 2am) or on manual trigger. It checks out the code, runs the documentation scanner, calls the Claude API for each undocumented item, and opens a PR with the results.

The workflow file is included in the automation download.

Step 2: The Documentation Scanner

The scanner is a Python script that walks your repository and identifies functions and classes without documentation. It handles Python (missing docstrings), JavaScript/TypeScript (missing JSDoc), Go (missing doc comments), and Java (missing Javadoc).

For each undocumented item, the scanner extracts:

This context package is what gets sent to Claude.

Step 3: Generate Documentation with Claude

The Claude prompt provides the full context package and instructs Claude to generate documentation in your chosen format. The prompt specifies:

Claude returns the complete documented version of the function. The scanner replaces the undocumented version in a copy of the source file.

Step 4: Create the Pull Request

After processing all undocumented items in a batch, the workflow creates a single pull request with all documentation additions. The PR includes:

Engineers review the PR like any other. They can approve documentation that looks correct, edit documentation that needs refinement, or close specific functions they want to document manually. The PR is not auto-merged.

Step 5: Configure Quality Thresholds

Set a minimum quality threshold in the configuration file. If Claude's confidence in its documentation for a specific function is low (because the function is too short to understand, or uses highly domain-specific terminology), the scanner skips that function and adds it to a "needs manual documentation" list in the PR description.

Functions shorter than 5 lines are skipped by default. Functions with no clear return value or side effects are flagged for human documentation.

Step 6: Enforce Going Forward

Once the backlog is documented, add a GitHub Actions check that flags new undocumented functions in pull requests. This is lighter than the full AI PR Review workflow: it simply identifies functions without documentation and comments on the PR asking the author to add documentation before merging.

The combination, backlog cleared by AI, new functions flagged by the check, produces a fully documented codebase within 90 days of deployment.

Part 3: Get the Automation

The WorkplaceAI Code Documentation Automation scans your repository, generates documentation for every undocumented function and class, and submits a pull request for engineering review, on a weekly schedule.

What you get:

How it works:

1. Purchase the Code Documentation Automation (one-time, $79)

2. Receive your unique activation key by email

3. Visit workplaceai.ai/activate and enter your key

4. Download the workflow files

5. Copy the YAML to `.github/workflows/`

6. Add your Anthropic API key to GitHub Secrets

7. Trigger a manual run, your first documentation PR opens within minutes

Cost per function documented: Approximately $0.002 in Claude API costs. For a codebase with 1,000 undocumented functions: approximately $2.00 for the initial documentation pass.

Coming next in the WorkplaceAI.ai Engineering & DevOps AI series: