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.
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.
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:
Once you can answer those, the prompt almost writes itself. Documentation is just structured empathy for a specific reader.
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.
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.
Weak prompt
write a readme for my project
[pastes 800 lines of source code]
You get a generic README with sections like "Installation", "Usage", and "Contributing" — all containing variations of "see the code". No quickstart, no real example, no explanation of why this project exists or who should pick it up.
Strong prompt (project README)
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]
You now have an audience, a question to answer, a structure, a tone, and the actual code. The README will be useful instead of generic — and it will tell honest readers when not to use the project, which is the single biggest trust signal a README can give.
Strong prompt (docstring)
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.
Notice the explicit instruction not to restate implementation. That single sentence is the difference between a useful docstring and a paraphrase of the code.
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.
Find an internal service in your codebase with a thin or missing README. Identify its audience (probably future teammates) and their main question. Write a prompt for a new README and generate it. Show it to someone who has never worked on that service. Do they understand it?
Pick a function in your project that has no docstring. Write a prompt that asks for a behaviour-first docstring — explicitly forbidding the AI from restating implementation. Compare the result to a generic "explain this function" prompt.
Take an existing README from a project you maintain. Paste it into the AI and ask:
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?
Sign in to join the discussion and post comments.
Sign inPrompt Engineering for Business & Productivity
Use AI to work smarter — automate tasks, make better decisions, and communicate professionally. 12 practical business prompt tutorials for professionals.
Foundations of Prompt Engineering
The must-know basics of prompt engineering. Learn what prompts are, how AI models read them, and how to write clear instructions that get great results.
Prompt Engineering for Image Generation
Turn words into stunning visuals. Master AI image generation tools like Midjourney, DALL·E 3, and Stable Diffusion with 18 focused tutorials — from first prompt to full brand identity.
Prompt Engineering Projects & Real-World Applications
Twelve hands-on projects that turn prompt engineering theory into a portfolio. Build chatbots, content generators, RAG systems, and more.
Prompt Engineering for Specific AI Tools
Tool-by-tool mastery — deep dives into ChatGPT, Claude, Gemini, GitHub Copilot, Midjourney, Stable Diffusion, and more. Learn the exact prompting techniques each platform rewards.
Prompt Engineering for Data Science & Analytics
Supercharge your data workflows with AI. 15 practical tutorials on using prompt engineering for data cleaning, EDA, machine learning, SQL, visualisation, and more.