How Do You Get Claude to Write Docs With Examples That Run?
Ask Claude to open the page with the smallest example that actually works, then explain it, then state the rule. Give it your real code or API reference so it isn't guessing, and have it run the example before you publish it. A doc whose first example fails loses the reader's trust straight away.
Write a doc page for [feature or function]. The reader is [who] and they want to [goal]. <reference> [paste the real function signature, API reference or source file] </reference> Structure: 1. The smallest complete example that works: real names from the reference, all imports, no placeholders except [API key]. Show the expected output. 2. What this example does, in 3 sentences or fewer. 3. The general rule or parameters, as a short table. 4. The 2 or 3 edge cases most likely to trip this reader up. If you can run the code, run it and tell me the real output. If you can't run it, for example because it needs network access or a private package, say so clearly at the top. Don't use a function or parameter that isn't in the reference.
- 1Smallest working exampletop of the page
- 2What it shows
- 3The general rule
- 4Edge cases
Try it now
- 1Check Settings > Capabilities to confirm Code execution and file creation is on (Create and edit files in the newer layout).
- 2Paste the prompt with your real reference material, and send it.
- 3Run the example yourself, on a clean machine if you can. Paste any error back into the chat.
- 4You'll know it worked when the example runs exactly as written and its output matches the page.
Use it when
API references, quickstarts, SDK guides, CLI docs and internal how-tos. It works outside code as well, such as a spreadsheet formula, a config file, or a filled-in template for a process.
Skip it when
Conceptual pages where the reader needs a mental model first, such as "how our permission system is structured". A diagram or short explanation should come first there. Also skip a runnable sample for destructive operations. Show the command with clear warnings rather than something readers will paste blindly.
Why it works
Readers often copy the example first and read the explanation only if something breaks. An example also pins the explanation to specifics, and it's harder to be vague about a function call than a concept.
Claude can test its own examples in some cases. With Code execution and file creation on, it works in a sandbox, and Anthropic's API docs describe that tool as running Python and Bash. Network access depends on your plan: Anthropic says egress is on for Free, Pro, Max and Ultra so Claude can install approved packages, limited to package managers on Team, and off by default on Enterprise. So a call to your private API may not run there. If a sample can't be run, Claude should say so rather than leaving you to assume it passed.
Example
Say you're documenting a Python function, export_invoices(start, end, format="csv"), for customers on your SDK. You paste the source file and the changelog. The first example is three lines: an import, the call with two real dates, and a printed row. Your private package isn't in Claude's sandbox, so it can't run that, and the prompt tells it to say so. You run it yourself, find the date format is rejected, paste the error, and the doc gets fixed before anyone sees it.
Going further
For docs that sit in a repository, use Claude Code, which Anthropic describes as reading your codebase, editing files and running commands. It works in your project, where your packages are installed. A chat is fine for writing the page, but a coding session is the better test.
Examples also steer later output. Anthropic's guide says to wrap examples in <example> tags and suggests 3 to 5 for best results. Paste two or three of your best existing doc pages that way, and new pages will tend to follow the same format. Keep them diverse, because Anthropic warns that overly similar examples can teach unintended patterns.
Common mistakes
- Asking for docs from a feature name alone. Claude may invent plausible method names, so paste the reference and forbid anything outside it.
- Accepting "..." or "your code here" in a first example. The reader can't run it, and that's the point of the example.
- Assuming a code block in chat was tested. Unless Claude actually ran it and showed output, treat it as untested.
- Expecting the sandbox to reach your staging API. Network access varies by plan and admin settings, and a private system is usually out of reach.
Sources
- Create and edit files with Claude, Claude Help Center
- Files API, Claude Platform Docs
- Prompting best practices, Claude Platform Docs
- Claude Code overview, Claude Code Docs
Checked 6 November 2026. Products change often, so confirm details with the vendor.