Gains:
- Ability to produce README, docstring and changelog drafts based on target audience and source with AI
- Ability to separate the 'what/how' and 'why' layers in documentation and add the 'why' as a human
- Verifying the installation steps by personally running them and making the document a part of the code change
The most frequently neglected but longest-lasting part of software is documentation. The code is readable even after months; The person who wrote it is gone, the context is forgotten, and only what was written remains. A good README (introductory document that explains what a project is and how to install and run it), explanatory code comments and an up-to-date API documentation (a reference that explains how to use an interface) directly determines the speed of a team. AI takes a lot of the “writing fatigue” out of documentation — but it comes with a trap: AI can infer from code what it does, but often can't know why it's done that way.
In this unit, you will learn how to produce README, code comment, docstring (comment block written per function/class), API document and changelog with AI; and how to humanly preserve the most valuable part of documentation: the “why.”
Distinction between "What" and "Why"
There are two layers of documentation. The first is what/how: "this function sorts a list", "run this command to install". These can be extracted from the code and structure; AI excels here. Secondly, why: "why did we make this service asynchronous rather than synchronous", "why is this limit value 30 seconds", "why did we choose this library over the other". These are not written in the code; It is the product of design decisions, constraints, and past pain.
AI doesn't know "why"; At best, it makes up a reasonable guess—which is dangerous, because a wrong reason is worse than no reason at all. So the division of labor is clear: AI drafts the “what/how,” you add the “why.” The most valuable comment is the one that says what the code can't say.
Tip: Don't repeat with a comment what the code itself clearly says (like i = i + 1 // increase i by one). AI sometimes produces such redundant comments; Eliminate them and devote your energy to “why” comments.
Step by Step: Documentation Generation with AI
- Specify the target audience. “A developer just starting out,” “the external team that will use this API,” “the future me” — the audience sets the tone for language and depth.
- Give the source. Add the relevant code, existing README, example usage to the prompt. An unsourced document is an invitation to fabrication.
- Imposition structure. Standard sections for README (Purpose, Installation, Usage, Configuration, Contribution), project format for docstring.
- Mark the "why" spaces. Ask the AI to mark decisions for which it doesn't know the rationale as "a 'why' note is required here"; Then you fill in those blanks.
- Verify. Actually run the installation steps; try the sample code. A README that doesn't work is worse than no README at all.
Three Mini Cases
Case 1 — README accelerated onboarding. An open source tool's README was missing; New contributors struggled with the installation for an average of 2 hours. The team gave the installation scripts and package.json to AI and drafted a structured README, then ran the steps themselves on a clean machine and added the two missing dependencies. Installation time for subsequent contributors decreased to an average of 25 minutes.
Case 2 — The made-up “why” trap. A developer asked the AI for a comment next to a timeout value (timeout=30). The AI wrote a reasonable but incorrect justification "to tolerate high network latency"; the real reason was a downstream service's contractual 30-second limit. The misinterpretation led a subsequent developer to unnecessarily increase the value, leading to an incident. Lesson: the code owner must verify the justification.
Case 3 — The Docstring standard has become automated. A auxiliary module with 40 functions had no docstrings. The AI was given the project format (Google style) and produced parameter, return and exception descriptions for each function; The developer reviewed these and fixed a few incorrect type declarations. Documenting 40 functions went down from about half a day to an hour.
Four Copiable Templates
Structured README draft:
Target audience: {{e.g. new contributor}}.Write a draft README based on the files below. Sections: Purpose, Features, Requirements, Installation, Operation, Configuration, Testing, Contribution. Extract installation/running commands from actual files; FITTING. Mark the places you are not sure with "[VERIFY]". Source: {{package.json / scripts / sample code}}
Docstring/API reference:
Write docstring to these functions in {{project style: Google/NumPy/JSDoc}} format: short summary, parameters (type + meaning), return, exceptions thrown, 1 short example. Don't repeat what the code CLEARLY says. Mark design decisions that require "why" as "[WHY NECESSARY]", do not write a fabricated justification.{{code}}
Remove spaces for "why" comment:
In this code, the next developer might ask "why is this so?" (magic numbers, unusual decisions, workarounds). Give a comment SKELETON for each, but leave the rationale BLANK; I will fill in the justification.{{code}}
Changelog/PR statement:
Write a {{changelog entry / PR description}} from the diff below. Format: What changed (in user language), Why (issue: {{...}}), Breaking change (if any), Has it been tested. Adjust technical jargon to target audience.{{diff}}
Weak prompt / Strong prompt
Weak: "Write a README for this project."
Strong: "Target audience: a developer cloning this repo for the first time. Based on the attached package.json, docker-compose.yml and scripts/ folder, write a draft README with Purpose, Requirements, Installation, Operation, Testing, Contribution sections. Extract the commands from these files, do not make them up; mark anywhere you are not sure with [VERIFY]."
The strong version gives the audience, the source, the structure, and the “make it, mark it” rule; so that the document is based on real files and the places to be verified are clearly visible.
Document type
AI does well
Human adds/verifies
README installation
step outline
Run the steps and confirm
Docstring/API
Structure, parameter, type
Correct type and "why"
Code comment
"What he's doing" summary
"Why is this" justification
Changelog/PR
first draft
Impact and accuracy
Architectural decision (ADR)
skeleton
Real decisions and compromises
Documentation Requires Maintenance
The most dangerous aspect of a document is when it appears true even though it is false. When the code changes and the document is not updated, it actively misleads the reader. AI makes updating easy: issue a diff and ask “which parts of the document does this change affect?” you may ask. But it's the process that ensures up-to-dateness — make the documentation update part of the code change (PR's acceptance criterion). AI accelerates; The team builds discipline.
Caution: Do not publish without verifying the installation steps in a README. A "probably work" document can ruin a new developer's first day and erode trust. Run the steps yourself in a clean environment.
Common mistakes
- Getting the “why” to fit the AI. False justification is worse than no justification; The code owner should write the design reason.
- Not verifying the installation steps. README that doesn't work destroys trust.
- Unnecessary comment repeating the code. It produces noise, obscuring real "why" interpretations.
- Not specifying the target audience. A document that is unclear to whom it is written is of no use to either the novice or the expert.
- Separating the update from the process. If the document is not updated with the code it quickly becomes misleading.
In summary
AI takes much of the mechanical burden out of documentation: quick drafts README, docstring, API reference, changelog and PR descriptions. But it cannot know the "why", which is the most valuable layer, and it is dangerous to make it up. The division of labor is clear: AI produces the “what/how,” you add the “why.” Specify the audience, provide resources, impose structure, mark places to fit, and verify each installation step by running it yourself. Make documentation an integral part of the code change.
Application task
Choose a module or small project whose documentation is missing or outdated. First generate an outline from AI with the “structured README draft” (or docstring) template; Be sure to give the source and target audience. Then go through each point where the AI has marked [VERIFY] or [WHY NEEDED]: actually run the setup steps and fill in the design “whys” with your own knowledge. Note how many steps need to be fixed and how many “whys” you added.
checklist
- [ ] In the documentation, I distinguish the "what/how" and "why" layers.
- [ ] I don't make the AI make up the "why", I add it myself.
- [ ] I give the prompt the target audience and the actual source files.
- [ ] I verify the [VERIFY] points marked by the AI by personally executing them.
- [ ] I eliminate unnecessary comments that repeat the code.
- [ ] I'm making the documentation update part of the code change.