Code Documentation with AI

🔄 Quick Recall: In the previous lesson, you wrote user guides and tutorials. Now you’ll focus on code documentation — the documentation that lives alongside your code: README files, inline comments, changelogs, and architecture decision records.

Code documentation bridges the gap between code that a computer can execute and knowledge that humans can understand. AI generates first drafts, detects documentation drift (docs that no longer match the code), and maintains consistency as the codebase evolves.

README Files

AI prompt for README generation:

Generate a comprehensive README for my project. Project: [DESCRIBE — what it does, tech stack, audience]. Repository structure: [DESCRIBE OR PASTE TREE]. Generate: (1) Title and one-line description, (2) Badges — build status, version, license, (3) What it does — 2-3 sentence description of the problem it solves, (4) Quick start — minimum steps to get running (install, configure, run), (5) Usage examples — 3-5 common use cases with code, (6) Configuration — environment variables, config files, with defaults, (7) API reference — key functions/endpoints with brief docs, (8) Contributing — how to set up the dev environment, run tests, submit PRs, (9) License. The quick start should work in under 5 minutes for someone who has never seen this project.

README quality tiers:

Inline Comments

AI prompt for comment quality audit:

Audit the comments in this code file. Code: [PASTE]. For each comment: classify as (1) WHAT-comment — restates what the code does (usually noise, should be removed), (2) WHY-comment — explains the reason behind a decision (valuable, keep), (3) WARNING-comment — alerts to non-obvious behavior (valuable, keep), (4) TODO-comment — marks incomplete or planned work (track in issue tracker). Then identify: code sections that NEED comments but don’t have them — non-obvious algorithms, magic numbers, workarounds, regex patterns, and intentional deviations from conventions.

✅ Quick Check: Which of these comments is useful? (A) // Loop through users before a for loop over users. (B) // Use insertion sort here — array is nearly sorted, and insertion sort is O(n) for nearly sorted data vs O(n log n) for quicksort before a sorting call. (Answer: B is useful because it explains WHY an unusual choice was made. A is noise — the code already says “loop through users.” If you deleted A, readability doesn’t change. If you deleted B, a future developer might “optimize” by switching to quicksort, making performance worse.)

Changelogs

AI prompt for changelog generation:

Generate a changelog entry from these git commits. Commits: [PASTE GIT LOG OR DESCRIBE CHANGES]. Format using Keep a Changelog conventions: (1) Added — new features, (2) Changed — changes to existing functionality, (3) Deprecated — features that will be removed, (4) Removed — features that were removed, (5) Fixed — bug fixes, (6) Security — vulnerability fixes. Write each entry from the user’s perspective — not “refactored the payment module” but “Payment processing is now 40% faster.” Group related commits into single entries. Flag breaking changes prominently.

Architecture Decision Records

AI prompt for ADR creation:

Create an Architecture Decision Record for this decision. Decision: [DESCRIBE — what was decided and roughly why]. Context: [THE SITUATION THAT LED TO THE DECISION]. Generate an ADR with: (1) Title — short descriptive title (e.g., “Use PostgreSQL for primary database”), (2) Status — proposed / accepted / deprecated / superseded, (3) Context — what was the situation, what constraints existed, (4) Decision — what was decided, (5) Alternatives considered — each alternative with pros and cons, (6) Consequences — positive and negative implications of the decision. Keep it under one page. The goal: a future developer can understand why this decision was made without asking anyone.

Documentation Freshness

AI prompt for drift detection:

Compare this documentation against the current codebase and identify outdated sections. Documentation: [PASTE OR DESCRIBE]. Codebase state: [DESCRIBE CURRENT — package versions, API endpoints, configuration options, etc.]. Find: (1) version mismatches — docs reference old versions, (2) renamed/removed items — docs reference functions, endpoints, or config that no longer exist, (3) missing items — new features or options that aren’t documented, (4) incorrect examples — code examples that wouldn’t work with the current version. For each issue: the specific location, what’s wrong, and the corrected content.

Key Takeaways

• Comments should explain WHY, not WHAT — “increment i by 1” is noise, “skip the header row” is valuable. AI audits comments and identifies which add value, which are noise, and where comments are missing for non-obvious code
• README drift is inevitable because code changes faster than docs — automated monthly freshness checks (AI compares README against codebase, opens a PR with updates) prevent drift from accumulating into a major rewrite
• Architecture Decision Records capture the WHY behind decisions that code alone can’t explain — AI generates ADRs from meeting notes or Slack threads, turning a 30-minute task into a 5-minute review
• Changelogs should be written from the user’s perspective: not “refactored payment module” but “payment processing is now 40% faster” — AI converts developer-focused git commits into user-focused changelog entries
• Documentation freshness is a maintenance problem, not a writing problem — the solution is automated drift detection that catches discrepancies monthly, not heroic manual review efforts

Up Next

In the next lesson, you’ll learn editing and style — applying plain language principles and style guides to technical content with AI-assisted editing that improves clarity.