Documentation
Documentation fails in predictable ways: it describes the happy path and stops, it repeats what the code already says, it was accurate eighteen months ago, and it is written for the person who built the thing rather than the person meeting it. These prompts are written against those failures. They ask for the reader's actual starting state, insist on working examples over descriptions, require the limitations section to be honest, and in the audit prompts they hunt for the sentence that quietly stopped being true. Use them on a page you are about to publish, or on one you inherited and do not trust.
36 prompts in 5 groups
Documentation21 categories
Getting someone started
READMEs, setup guides, onboarding and glossaries for the person meeting this for the first time.
- Structure a README that gets someone runningLongA project with working code and a README that says only its name.
- Write a getting-started guide that ends in a winLongNew users install the thing and then don't know what to do next.
- Build a glossary for this domainLongNew starters keep asking what a word means and getting three answers.
- Write onboarding docs for a new teammateLongSomeone starts Monday and the setup knowledge lives in three people's heads.
- One-line descriptionShortThe first sentence of a README, or a repo description field.
- What is this README missing?ShortBefore publishing a README you wrote in one sitting.
- Summarise this for a newcomerShortSomeone joins next week and this is the thing they'll meet first.
- Find the hidden prerequisitesMediumSetup instructions that work perfectly on your machine.
- Turn this into stepsMediumAn explanation that someone is supposed to follow along with.
Reference and API docs
The lookup layer: function docs, config options, error codes and examples worth copying.
- Generate API reference from this codeLongA module whose public surface needs documenting properly, not just typed.
- Write the doc comment this function deservesLongA function whose name and types don't tell the whole story.
- Document a config option properlyLongAdding a setting that someone will have to tune under pressure.
- Write examples that aren't toysLongDocs whose only example is foo and bar and helps nobody.
- Document every error this can returnLongUsers hit an error code and find nothing when they search it.
- Write the exampleShortA reference entry with no example, which is most of them.
- Explain this optionShortA setting whose name tells you nothing about what it does.
- Document this errorShortAn error users will search for and find nothing about.
Releases and decisions
Changelogs, migration guides and decision records that explain what changed and why.
- Write changelog entries from these commitsLongCutting a release and the commit log is not a changelog.
- Write a migration guide for a breaking changeLongShipping a major version and users have to change their code.
- Write an architecture decision recordLongA decision was made in a meeting and will be questioned in a year.
- Changelog line for this changeMediumOne commit that needs one honest user-facing line.
Runbooks and support
What to do at 3am, the failures that keep arriving, and the limits nobody wrote down.
- Write a runbook for someone woken at 3amLongAn alert exists and the only person who knows what to do is on holiday.
- Build a troubleshooting page from real failuresLongThe same three problems keep arriving in your support inbox.
- Make the docs honest about what this can't doLongDocs that read like marketing and leave users to discover the edges themselves.
- Turn a support thread into a docs pageLongYou just answered the same question for the fourth time in a ticket.
- Write the limitations bulletsMediumDocs that describe the happy path and stop.
Editing and auditing docs
Finding what is stale or undocumented, cutting what the code already says, rewriting for the reader.
- Which of these comments should exist?LongA file dense with comments that mostly narrate the code.
- Explain this for a non-technical readerLongWriting for support, sales, or a stakeholder who needs the shape not the detail.
- Audit these docs for what is no longer trueLongDocumentation that was written once and never checked against the code again.
- Turn an internal spec into user-facing docsLongThe feature shipped and the only writing about it is the design doc.
- Does this comment earn its place?ShortA comment you are not sure is worth the line it occupies.
- What is undocumented here?ShortCode whose real behaviour has drifted past its documentation.
- Name this sectionShortA heading nobody will ever find by searching.
- Tighten this paragraphShortDocs prose that takes three sentences to say one thing.
- Check the docs against the codeMediumA page you inherited and have no reason to trust.
- Rewrite the top of this pageMediumA page that buries the one thing everybody came for.
Got one that isn't here?
Send a prompt you keep coming back to. A person reads every one.
Suggest a prompt