Style guide

How we write docs.

The Engine’s docs aim to be warm, conversational, respectful of the reader’s time, and concrete. This page is the long version of those vibes, with concrete rules.

Voice

• Second person for tutorials and how-tos. “You’ll send a request, read the response, and…” A tutorial is a thing the reader is doing. Address them.
• Third person for reference and conceptual. “The Engine returns…” “When the agent loop encounters…” Reference and explanation are about the system, not about the reader.
• Active voice. “The Engine returns” not “is returned by the Engine.”
• Present tense for behavior. “The Engine retries” not “the Engine will retry.”
• Past tense only for incidents. “On 2026-04-12 the Engine returned 500s for 12 minutes.”

Tone

• Warm, not cute. No emoji in technical content. No exclamation marks.
• Confident, not arrogant. State what the system does. Don’t apologize for what it doesn’t.
• Specific, not vague. Replace “many users” with a number or with “users who,” etc.

Structure

• Lead with the thing. Don’t open with three paragraphs of context before showing code. Show the smallest working example first; explain after.
• One thought per paragraph. If a paragraph has more than one argument, split it.
• Short sentences. Long sentences hide long thinking. Cut ruthlessly.
• Sentence-case headings. “Streaming events” not “Streaming Events” or “STREAMING EVENTS.” Product names keep their casing.

Headings

• Use ## for major sections, ### for sub-sections. Avoid ####. If you find yourself reaching for it, the page wants to be split.
• Heading text should answer “what’s in this section?” — not “let’s talk about X.”
  • Bad: “About authentication”
  • Good: “How requests are authenticated”

Lists

• Bullets when order doesn’t matter.
• Numbered when order matters.
• One sentence or short clause per bullet. If a bullet runs to three lines, it wants to be a sub-section instead.

Code

• Always tag code blocks with their language: bash, python, js, ts, json, http, sql.
• Code samples are real and tested. If the code is hypothetical, mark it # pseudocode.
• Use real values, not placeholders, where possible. claude-sonnet-4-5 beats <your-model>.
• Wrap inline code in backticks: task_id, X-Engine-Key.

Tables

• Use tables for parallel data with the same columns per row (env vars, endpoints, error codes).
• Use prose for narrative information.
• First column is the key being defined. Subsequent columns are attributes.

Linking

• Link the first time you mention a concept; not every time.
• Use descriptive link text: “see the agent loop” not “see here.”
• Internal links use relative paths. External links use full URLs.
• Cross-link reference pages from concept pages and back.

Diátaxis discipline

Every page is one of:

Mode	Tense	Purpose	Example
Tutorial	2nd person, present	Learn-by-doing	”Quickstart”
How-to	2nd person, present	Solve a specific problem	”Migrate from v1 to v2”
Conceptual	3rd person, present	Build a mental model	”The agent loop”
Reference	3rd person, present, scannable	Look up a fact	”POST /execute”

Don’t blend modes within a page. If a tutorial wants to explain why, link to the conceptual page. If a reference wants narrative, link to the how-to.

Internal vs. external

• Anything not safe for public eyes — roadmap, customer names, cost figures, threat-model attacker profiles, anything touching live credentials — goes on a page with internal: true in frontmatter.
• The public build strips those pages. Don’t rely on the strip — assume every line you write under internal: true could leak, and write carefully anyway.

Diagrams

• Use Mermaid for all diagrams (Mintlify renders it inline). Mermaid produces real boxes, arrows, and clusters that render legibly in every browser.
• Avoid ASCII art — it’s brittle, hard to maintain, and looks bad in most fonts.
• Always explain the diagram in prose immediately after.

House rules for code samples

• HTTP requests show full headers. No assumed defaults.
• Python uses httpx. Node uses built-in fetch.
• Show error handling in real samples; skip it only when the page is explicitly about the happy path.
• Don’t import what you’re not using.

Things we don’t do

• We don’t use marketing words. “Powerful,” “robust,” “best-in-class,” “next-generation.” Cut them.
• We don’t use “simply” or “just.” If it’s simple, it doesn’t need saying. If it’s not, the word is dishonest.
• We don’t link to GitHub line numbers — they rot. Link to the file or to the relevant doc page.
• We don’t write FAQ pages as a substitute for fixing the docs. If the same Q surfaces three times, fix the documentation that should have answered it.