Docstrings and user guides answer different questions
A docstring lives next to the code it describes. It tells another developer what a function does, which arguments it accepts, what it returns, and what happens when an input is wrong. It assumes the reader already knows the codebase and only wants to confirm a detail.
A user guide serves a different reader. That person met the tool ten minutes ago, has one job to finish today, and will not dig through a list of parameter names to find the command that starts the work.
Treat conversion as translation rather than copy and paste. The docstring stays the source of truth for behaviour. The guide supplies the plan of action.
- The docstring asks: what does this function accept?
- The guide asks: what should I type first?
- The docstring lists every parameter.
- The guide lists only the parameters the first run needs.
- The docstring reports failures.
- The guide tells the reader what to do about a failure.
Keep the facts from the docstring and change the framing around them. That single habit removes most of the confusion newcomers run into.
Read the whole docstring before writing a single line
Skim the docstring once to see its shape, then read it again with a notebook open. The second pass is where the guide takes form.
Answer these questions before you write anything:
- Who calls this code, and in what situation?
- Which arguments are required on the first attempt?
- What does the caller get back, in plain words?
- Which failures does the code already describe?
- Which values are defaults a beginner can ignore for now?
Defaults deserve extra attention. When a parameter is optional and already filled in, tell the reader to leave it alone on the first run. Newcomers do not need the full surface area of a tool on day one; they need the shortest path to a working result.
Error text is a gift. A docstring that names a bad input, a missing key, or an out-of-range value hands you a troubleshooting list for free. Rewrite each message as a symptom the reader might see, then give the fix in one sentence.
Finally, collect every term you cannot explain without reaching for more jargon. If you cannot define it in one plain sentence, the reader will not follow it either.
Turn parameter lists into a first-run walkthrough
Start from the smallest example that works end to end. Show one call, one output, one moment of success. Everything else waits.
Then walk the parameters in the order a beginner meets them:
- Required values come first, renamed in everyday words.
- Optional values follow, each with a note on when it earns its place.
- Each step gets one instruction and one sentence of reason.
- Exact strings stay exact, so the reader can paste them.
Take a concrete case. A technical spec might say base_url: string and stop there. A user guide says: paste this host, https://api.fastapirelay.com, then explains the one detail that trips people up. Claude Code and Gemini CLI take the bare host. OpenAI-compatible SDKs, including Codex, add /v1 to the end.
SwiftRelay works with Claude Code, Codex, Gemini CLI and any OpenAI-compatible SDK, so spelling out the host form once covers all of them. A guide that names the shapes a reader actually uses stays honest.
Keep parameter names in a small reference at the bottom for readers matching what they see on screen. The walkthrough itself should read like instructions to a friend.
Spot the translation traps before they reach the reader
Some docstring habits survive translation and quietly break the guide. Watch for these:
- Words like initialise, serialise, or payload that a newcomer has to decode before the sentence makes sense.
- Passive voice that hides who does what.
- Hidden defaults that change behaviour without appearing in the example.
- Hedging words such as may or should where the reader needs a clear yes or no.
- Error messages written for a stack trace rather than a person.
Fix each one the same way: replace the word with its plain meaning, name the actor, surface the default, and add one short example. A parameter called max_tokens becomes a limit on how much the model writes, with the note that billing is counted per token, so the limit also caps what the run costs.
Model names are the exception to the simplify rule. When a guide names a model, copy the name exactly as the dashboard shows it, for example Claude Haiku 4.5 or Gemini 2.5 Flash. A renamed model sends the reader to the wrong place.
Run the guide from a clean slate before you publish
Open a fresh terminal and follow your own text literally. Each time you reach for memory, stop and write down what was missing. That note is the next sentence to fix.
Check the run in this order:
- Every command works from scratch, with no setup from an earlier step left behind.
- The host line is exact, and the reader can see which form their tool expects.
- The example output matches what the reader will see.
- Each failure in the docstring has a matching fix in the guide.
- The reader can stop after the first success and still feel finished.
A live endpoint makes this test realistic. Create a SwiftRelay account and point the walkthrough at it: new accounts receive a small gift credit, inviting friends earns 14% of their top-ups, and billing is metered per token, so a first run costs only what that run uses. Run the same guide against a couple of models to confirm the wording holds, since phrasing that fits a small fast call usually reads well for a larger one too.
If a step needs context from a later section, move that context earlier. Reading order is the hidden structure of a guide, and a newcomer will not jump backwards to understand forwards.
A checklist before the green light
Before you publish, run this list one last time:
- The title names the job the reader will finish.
- The first screen contains a working example, not an explanation.
- Every parameter has a plain-language meaning next to its real name.
- Every documented failure has a fix in the reader's words.
- Hosts, model names, and exact strings match what the reader will see.
- No leftover jargon appears without a short definition.
Docstrings keep evolving with the code, so treat the guide as a build artefact. When a docstring changes, re-run the walkthrough and adjust the sentences that touch it. The habit keeps the guide honest, and it keeps the next newcomer from guessing.