Using AI for Code Documentation and README Generation

Documentation is the part of software engineering that pays back the slowest but compounds the longest. AI can generate docstrings, READMEs, and architecture overviews in seconds — but it tends to produce bland, audience-less prose unless you steer it deliberately.

1. Introduction

The reason most code documentation is bad is that it is written for nobody in particular. AI inherits this default: ask for "documentation" and you get a flat description of what the code does — which is exactly what the code already shows. Useful documentation answers questions a reader cannot answer by reading the code itself: why does this exist? when should I use it? what should I avoid?

This tutorial gives you a prompt pattern that produces documentation tuned to a specific audience, with the right level of detail and the right things left out.

2. The Concept Explained

Every piece of documentation has an audience and a job. A docstring on a private helper has a different audience than a top-level README. A README for an open-source library has a different audience than an internal service README. Each combination needs a different tone, depth, and structure.

Three questions to answer before writing the prompt:

• Who is going to read this? A teammate, a new hire, an external user, your future self in six months?
• What decision are they trying to make? Should I use this? How do I configure it? How do I extend it? How do I debug it?
• What can be safely left out? Implementation detail is rarely what the reader needs.

Once you can answer those, the prompt almost writes itself. Documentation is just structured empathy for a specific reader.

The three documentation layers

Most projects need three layers of docs: inline docstrings (per function/class), module-level READMEs (per service or package), and a project README (the front door). Each one strips out detail and adds context. Don't ask the AI to write all three from the same prompt — they have different audiences.

3. The Problem Without This Technique

The common prompt is "write a README for this project". Without an audience or a goal, the AI generates a default README — useful for nobody, present for everyone.

write a readme for my project

[pastes 800 lines of source code]

4. The Solution

Write a README.md for the project below.

Audience: backend developers evaluating whether to add this library to
their Node.js project. Most have 2+ years of experience.

Reader's main question: "Should I use this instead of writing it myself
or pulling in a heavier alternative like `bull`?"

Project: `tinyqueue`
What it does: in-memory job queue with retry and exponential backoff,
zero dependencies, ESM and CJS, TypeScript types included.

Sections, in this order:
1. One-line elevator pitch
2. Why it exists (2–3 sentences, focus on what it does that bull/agenda don't)
3. Install (npm + pnpm)
4. Quickstart — one runnable code block, < 20 lines, that demonstrates
   adding a job and processing it with a retry policy
5. API reference — only the public exports, with one-line descriptions
6. When NOT to use this — be honest (no persistence, single process)
7. License

Tone: confident, direct, no marketing fluff.
Length: aim for ~250 lines.

Code attached below:
[paste main.ts and types.ts contents only]

Language: Python 3.11, using Google-style docstrings (matches our team style).

Function:

```python
def normalise_phone(raw: str, default_country: str = "IN") -> str:
    digits = "".join(c for c in raw if c.isdigit())
    if len(digits) == 10 and default_country == "IN":
        return f"+91{digits}"
    if digits.startswith("0") and default_country == "IN":
        return f"+91{digits[1:]}"
    return f"+{digits}"
```

Write a docstring that:
- One-line summary (imperative mood)
- Args block with type info
- Returns block
- Raises block (or "Does not raise.")
- One usage example showing a 10-digit Indian number being normalised
- One caveat about ambiguous inputs (e.g. numbers with country code but no '+')
- Do NOT restate the implementation. Focus on behaviour and contract.

5. Step-by-Step Breakdown

1. Name the audience. Junior dev? Senior engineer evaluating the library? An SRE on call at 2am?
2. State the reader's main question. "Should I use this?" / "How do I configure X?" / "How do I extend this?"
3. Pick the layer. Docstring, module README, or project README. Different layers, different prompts.
4. Specify the structure. Section headings, order, length per section. Documentation has a shape — don't let the AI choose it.
5. Tell it what to omit. "Don't restate the implementation", "no marketing fluff", "skip the contributing section". Pruning is half the job.
6. Include the actual code. Without it, the AI will document an imaginary version of your project.

Tip: For project READMEs, the most valuable section is usually "When NOT to use this". It is also the section AI omits by default. Add it explicitly to your prompt.

6. Practice Exercises

What sections of this README are useless? What sections are missing? What would a developer evaluating this project want to know that I haven't told them?

7. Key Takeaways