Case Study 01: Documentation Rescue — Using AI to Create Comprehensive Documentation for an Undocumented Project

Background

Mira Patel joined DataForge Analytics as a senior developer in October 2025. Her first assignment was to take ownership of an internal Python library called pipeline-core, a data transformation engine used by four different product teams across the company. The library processed financial transaction data, applying validation rules, currency conversions, and compliance checks before loading results into the company's data warehouse.

The library had been built over two years by a team of three developers, two of whom had left the company. The remaining original developer, Alex, was transitioning to a different team. When Mira opened the repository for the first time, she found 47 Python modules, 312 functions, 28 classes, and exactly zero documentation files. No README. No API reference. No architecture overview. No docstrings on 80% of the public functions.

The code worked. Tests existed for about 60% of the functionality (a decent test suite that Alex had insisted on). But understanding what the library did, how to use it, or why specific architectural choices had been made required either reading all 12,000 lines of code or asking Alex, who had two weeks left before his transition.

Mira faced a documentation rescue mission. She had two weeks to create enough documentation that the four product teams could continue using pipeline-core without Alex, and that future maintainers could understand the codebase. She decided to use AI assistants strategically to accomplish what would normally take months.

The Challenge

The specific documentation gaps were severe:

No README. New developers joining any of the four product teams had no way to understand what pipeline-core did or how to get started without scheduling a meeting with Alex.

No API Reference. The library had a public API of approximately 85 functions and 15 classes. Only 12 functions had docstrings, and those docstrings were incomplete, typically just a one-line description without parameter documentation.

No Architecture Documentation. The library used a pipeline pattern with plugin-based transformations, a custom retry mechanism for external API calls, and a specific approach to handling currency conversion that involved caching exchange rates. None of these design decisions were documented anywhere.

No User Guide. The four product teams had each figured out how to use the library through trial and error, Slack messages to Alex, and copying patterns from each other's codebases. Each team used the library slightly differently, and some were using internal APIs that were not intended to be public.

No Changelog. The library had 847 git commits across two years, but no changelog. Product teams could not tell which version introduced which features or which versions contained breaking changes.

The Approach

Mira designed a five-phase documentation rescue plan, budgeting roughly two to three days per phase.

Phase 1: Knowledge Extraction from Alex (Days 1-2)

Before touching any AI tools, Mira spent two days with Alex in structured knowledge transfer sessions. She did not ask Alex to write documentation. Instead, she interviewed him using a prepared question framework:

  1. Architecture overview: "Walk me through how a transaction flows from input to the data warehouse. What are the major components?"
  2. Key decisions: "Why did you choose a plugin architecture for transformations? What alternatives did you consider?"
  3. Gotchas: "What are the top five things that have tripped up other developers using this library?"
  4. Internal vs. public API: "Which functions and classes are intended to be used by product teams, and which are internal implementation details?"
  5. Known issues: "What are the known limitations or areas where the design is not ideal?"

Mira recorded these sessions (with Alex's permission) and took detailed notes. This raw knowledge would be the seed material for AI-assisted documentation generation.

Phase 2: Automated Docstring Generation (Days 3-5)

Mira used the docstring analyzer approach described in this chapter's code/example-02-docstring-analyzer.py to assess the current state:

Docstring Coverage Report for pipeline-core
============================================
Total public functions: 85
Documented: 12 (14.1%)
Missing docstrings: 73 (85.9%)
Incomplete docstrings: 8 (9.4%)

Total public classes: 15
Documented: 3 (20.0%)
Missing docstrings: 12 (80.0%)

She then used a systematic AI-assisted workflow for each module:

  1. Feed the module's source code to the AI assistant
  2. Provide Alex's notes about the module's purpose and behavior
  3. Ask the AI to generate Google-style docstrings for every public function and class
  4. Review each generated docstring against the actual code behavior
  5. Run the existing test suite to verify her understanding

Here is an example of the prompt she used for a critical module:

I need docstrings for every public function and class in this
module. Here is the source code:

[pasted 400 lines of currency_converter.py]

Context from the original developer:
- Exchange rates are cached for 1 hour to avoid API rate limits
- The fallback rate is used when the external API is unreachable
- Rates are fetched from the ECB API, not a commercial provider
- The "stale rate" warning threshold is 24 hours

Please generate Google-style docstrings. For each function,
include Args, Returns, Raises, and a brief Example where
appropriate. Flag any behavior that seems unusual or that
you are uncertain about.

The AI generated docstrings that were approximately 80% correct on the first pass. The remaining 20% required corrections that Mira identified through code reading and test examination. Common issues in the AI-generated docstrings:

  • Invented behavior: The AI sometimes described behavior that was plausible but not present in the code (e.g., claiming a function supported a timeout parameter that did not exist)
  • Missing edge cases: The AI described the happy path accurately but missed error handling that the code performed
  • Incorrect type descriptions: The AI sometimes guessed wrong about generic types (e.g., describing a return as list[dict] when it was actually list[TransactionResult])

Mira corrected each issue and added the docstrings via pull requests, grouped by module, so they could be reviewed incrementally.

Phase 3: README and Architecture Documentation (Days 6-8)

With docstrings in place, Mira turned to higher-level documentation. She used the README generator approach (see code/example-01-readme-generator.py) to create a first draft, providing:

  • The project's directory structure
  • The pyproject.toml file
  • Alex's architecture overview notes
  • A list of the four product teams and their use cases

The AI-generated README draft was 1,200 words and covered the basics well. Mira expanded it to 2,500 words, adding:

  • A clear statement of what pipeline-core does and does not do
  • Installation instructions specific to the company's internal PyPI server
  • Three quick-start examples covering the most common use cases
  • A section on the plugin system with instructions for writing custom transformations
  • A "Public API" section listing which modules and classes were intended for external use

For architecture documentation, Mira wrote three ADRs based on Alex's knowledge transfer notes:

  • ADR-001: Plugin architecture for data transformations (why plugins instead of a configuration-based approach)
  • ADR-002: Cached exchange rate strategy (why 1-hour cache with 24-hour staleness warning)
  • ADR-003: Retry mechanism for external APIs (why a custom implementation instead of tenacity)

She used the ADR template system from code/example-03-adr-template.py and had the AI draft each ADR from her notes. She then reviewed and refined each one, adding context that only a human who had spoken with Alex could provide.

Phase 4: User Guide and Migration Notes (Days 9-11)

Mira discovered that the four product teams used the library differently, and some were using internal APIs directly. She created a user guide with two goals:

  1. Show the correct way to use the library for common tasks
  2. Provide migration paths for teams using internal APIs

She structured the user guide following the Diataxis framework:

  • Tutorial: "Processing Your First Transaction Batch" — a guided walkthrough for new developers
  • How-To Guides: Task-oriented guides for each major feature (custom transformations, currency conversion, compliance checks, error handling)
  • Reference: Auto-generated API reference from the newly written docstrings
  • Explanation: The ADRs and an architecture overview diagram

For the tutorial, she used an AI assistant to generate a complete walkthrough, providing the actual API and expected inputs/outputs. She tested every code example in the tutorial to ensure it worked.

Phase 5: Changelog Reconstruction and Process Setup (Days 12-14)

The final phase addressed the missing changelog and set up processes to prevent documentation from decaying again.

For the changelog, Mira used git log analysis combined with AI:

git log --oneline --since="2024-01-01" | head -200

She fed this to the AI with the instruction:

Here are the git commits for pipeline-core from the last year.
Group them into monthly releases (we release on the first of
each month) and format as a Keep a Changelog document. Focus
on user-facing changes. Ignore commits that are purely internal
refactoring unless they changed behavior.

The AI produced a changelog that captured the major changes. Mira reviewed it against the git diff for each month to ensure accuracy, particularly around breaking changes.

For ongoing maintenance, Mira established:

  • A pre-commit hook checking docstring coverage (must stay above 90%)
  • A pull request template requiring a changelog entry for user-facing changes
  • A quarterly documentation review calendar event
  • A CONTRIBUTING.md file explaining the documentation standards

Results

After two weeks, pipeline-core had:

  • 85 documented public functions with Google-style docstrings (up from 12)
  • 15 documented public classes (up from 3)
  • A comprehensive README (2,500 words)
  • 3 Architecture Decision Records
  • A user guide with tutorial, how-to guides, and reference sections
  • A reconstructed changelog covering the previous 12 months
  • CI checks preventing documentation regression

The impact was measurable:

  • Slack questions to Alex about pipeline-core dropped from approximately 8 per week to 1 per week within the first month after documentation was published
  • A new developer on one of the product teams onboarded onto pipeline-core in 2 days instead of the previous average of 2 weeks
  • Two of the four product teams voluntarily migrated away from internal APIs to the documented public API within a month

Lessons Learned

1. Human knowledge extraction is irreplaceable. The AI could generate docstrings from code and format ADRs from notes, but it could not extract the "why" from Alex's head. The two days spent in knowledge transfer sessions were the most valuable days of the entire project.

2. AI is excellent at drafting, not at verifying. The AI produced documentation that was approximately 80% correct. The remaining 20% required human verification against the actual code and tests. Never ship AI-generated documentation without review.

3. Start with docstrings, then build up. Docstrings provided the foundation for everything else. Once functions were documented, the README examples could reference documented behavior, the API reference could be auto-generated, and the user guide could point to specific functions.

4. Reconstruct history before it is lost. The changelog reconstruction was valuable but imperfect. Some context about why certain changes were made was already lost. If they had maintained a changelog from the start, this phase would have been unnecessary.

5. Process prevents regression. Documentation created without maintenance processes will decay. The CI checks, PR template, and quarterly reviews were as important as the documentation itself.

6. Documentation is a team investment, not a solo project. Mira's two-week sprint produced the initial documentation, but its long-term value depended on the entire team maintaining it. The CONTRIBUTING.md and documentation standards were essential for making this a shared responsibility.

Connection to Chapter Concepts

This case study demonstrates several key concepts from Chapter 23:

  • Section 23.1: Documentation as a first-class citizen — Mira treated documentation as a deliverable with the same priority as code
  • Section 23.2: README best practices — The README followed the five-question structure
  • Section 23.4: ADRs — Three ADRs captured decisions that would have been lost
  • Section 23.5: Docstrings — Systematic Google-style docstring generation
  • Section 23.6: User guides — Diataxis-structured user guide with tutorial and how-to sections
  • Section 23.7: Changelog — Reconstructed from git history with AI assistance
  • Section 23.10: Maintaining documentation — CI checks and processes for ongoing maintenance

The code supporting this case study is available in code/case-study-code.py.