A docs style guide before Friday’s API release

Your team needs an API quickstart before Friday’s release. An AI assistant produces a readable draft in minutes, but it calls the same credential an API key, access token, and secret. It also invents a retry setting. The sentences sound polished; the documentation is not ready.

A style guide gives the assistant a shared set of writing rules. It also gives reviewers something more useful than “this doesn’t sound right.” Start with one page that describes your readers, preferred language, document structure, and rules for uncertainty.

Define the reader and the next successful action

Before choosing a tone, identify who will use the page and what they need to accomplish. “Developers” is too broad. “Developers making their first authenticated request” gives the writer a clear target.

Add a short audience statement to your guide: “Readers understand HTTP but have not used our API. Help them send one successful request before introducing advanced options.” This prevents a quickstart from turning into a reference manual.

Include prerequisites, too. If readers need an account, a credential, and a supported runtime, require the documentation to name them before the first instruction.

Turn vague preferences into testable writing rules

“Be clear and friendly” is a useful intention, but a weak instruction. Replace it with rules that a writer and reviewer can apply consistently.

• Address the reader as “you.” Use “we” only when referring to the product team.
• Use direct instructions: “Create an API key,” not “An API key should be created.”
• Use sentence case for headings and name the task or concept in each heading.
• Define unfamiliar abbreviations on first use.
• Avoid claims such as “effortless,” “instant,” or “production-ready” unless the source material supports them.
• Explain what an action changes, especially if it deletes data or creates charges.

Keep exceptions explicit. A reference page may need precise technical terms that a beginner tutorial should introduce gradually.

Create a small vocabulary and example policy

List preferred terms alongside terms to avoid. For example: “Use API key; do not substitute access token.” Follow the product’s actual terminology, even when another phrase sounds more natural.

Then define what examples must contain. A request example might need an authentication method, a request body, an expected response, and a common failure case. Require placeholders for credentials, and forbid real customer information.

Preserve exact identifiers. An assistant may improve surrounding prose, but it must not rename parameters, change capitalization in configuration keys, or simplify command syntax. Those are interface details, not stylistic choices.

Separate writing rules from verified product facts

A style guide controls presentation. It cannot establish whether an endpoint exists or a feature is available. Give the assistant approved source material separately, such as an API specification, maintained reference pages, or tested examples.

Add a firm rule: “Do not invent endpoints, defaults, limits, prices, or supported features. If the supplied sources do not answer a question, flag the gap for review.” Keep those flags in the draft workflow rather than publishing them as customer-facing instructions.

When sources disagree, require escalation instead of a confident guess. A fluent explanation of the wrong timeout value is still wrong.

Attach the guide to a repeatable drafting prompt

Use a simple prompt structure: audience, task, approved sources, style guide, and required output. Ask the assistant to identify missing information before drafting when that information would change the instructions.

If you want to compare drafts across models, RelayVano is a practical option: its pay-as-you-go relay works with OpenAI-compatible SDKs, letting you keep the same prompt and review checklist. Sign up to test a short documentation sample before expanding the workflow.

Review one real page before expanding the guide

Test your first guide on a small page. Check terminology, follow the instructions, and run any commands in an appropriate test environment. Human review remains necessary even when the draft follows every writing rule.

Record repeated corrections and turn them into specific rules. Keep occasional preferences out unless they solve a recurring problem. A useful style guide is short enough to apply, concrete enough to check, and updated when the product or its readers change.