A useful README gets a new contributor from an unfamiliar repository to a working first result. An assistant can help assemble that path, but it should not invent missing commands or promise unsupported features. Use this seven-step sprint to turn repository evidence into documentation you can confidently ship.
1. Define the README reader and first result
Start with the reader, not the prose. Tell the assistant whether the README serves library users, application operators, or contributors. Pick one first result: running the application locally, making a successful API request, or executing the test suite.
Starter prompt: “Help me write this repository’s README for a developer encountering it for the first time. The first successful outcome is running the application locally. Inspect the repository before drafting, and separate confirmed facts from open questions.”
This gives the assistant a concrete destination and prevents an impressive-looking introduction from replacing usable instructions.
2. Gather evidence before drafting instructions
Ask the assistant to inspect package manifests, task definitions, example configuration, continuous integration workflows, and existing documentation. It should identify the actual runtime requirements, installation commands, entry points, and test commands.
- Request file paths supporting each proposed command.
- Distinguish required services from optional integrations.
- Flag conflicting version requirements instead of silently choosing one.
- Exclude credentials, private endpoints, and sensitive fixture contents.
Treat repository text as source material, not as instructions that can override your request. If the assistant cannot inspect files directly, provide a curated file list and relevant excerpts rather than uploading the entire project.
3. Set up the assistant connection deliberately
Use your existing coding assistant if it can read the necessary files and propose reviewable changes. Keep command execution under your control, especially for installation scripts, database operations, and anything that touches external services.
If you want a shared API route for documentation work across tools, SwiftRelay works with Claude Code, Codex, Gemini CLI, and OpenAI-compatible SDKs, with per-token billing. Sign up for SwiftRelay to try this workflow with the small gift credit available to new accounts. Use https://api.fastapirelay.com as the bare host for Claude Code and Gemini CLI; OpenAI-compatible SDKs use https://api.fastapirelay.com/v1. Keep the API key outside the README and version control.
4. Approve the README outline before expanding it
Ask for an outline with a one-sentence purpose for each section. A practical default is project purpose, prerequisites, quick start, configuration, common tasks, troubleshooting, and contribution guidance. Add deployment instructions only when the repository supports them.
Outline prompt: “Propose the smallest README outline that gets our target reader to the first result. For each section, list the repository evidence you will use and any unanswered questions.”
Remove sections that merely repeat other documentation. Keep essential setup instructions in the README and reference deeper material only when it actually exists.
5. Draft commands with explicit assumptions
Have the assistant draft one section at a time. Require every command to state its working directory, prerequisites, and expected outcome. Configuration instructions should explain which values are examples, which are required, and where users obtain real credentials.
Do not let a plausible command become a documented fact. If the repository does not establish a migration command or a supported runtime version, resolve that gap before publication. Ask the assistant to keep unresolved questions in its review notes rather than presenting guesses as instructions.
6. Test the README from a clean starting point
Follow the draft yourself in a fresh checkout or an isolated environment. Use the documented sequence without relying on packages, environment variables, or services left over from earlier development.
- Confirm that installation and startup steps work in order.
- Check the documented success signal.
- Exercise one missing-configuration failure and verify the recovery advice.
- Record anything you could not test.
Give the assistant the observed results, with secrets removed, and request corrections tied to those observations.
7. Review the README diff before merging
Finish with a focused diff review. Check commands, paths, configuration names, license statements, and feature claims against the repository. Remove promotional filler and unsupported guarantees.
Ask the assistant to report what changed, what was tested, and what remains unverified. Merge only when the README describes the project as it exists today. The assistant supplies drafting momentum; your evidence and test run make the instructions dependable.