Skip to main content
These rules exist so every page reads like it came from one writer. They apply to humans and to AI-generated drafts equally. If a draft violates them, fix the draft, not the rules.

​
Who we’re writing for

The reader is a marketer or founder who ran the free audit and clicked an issue to understand it. Assume they are smart and busy, and have no technical background. The reference links they clicked before landing here (MDN, W3C specs) made them feel stupid. Our job is the opposite.

​
Tone of voice

  • Plain language first. If a term needs a technical name, use it once, define it immediately in the same sentence, then use the plain version.
  • Second person. “Your site”, “your page”, never “the user’s website”.
  • Short sentences. Short paragraphs. Three sentences per paragraph is a good ceiling.
  • Confident and warm, not bubbly. No exclamation marks in body copy. No “simply” or “just”: if it were simple, they wouldn’t be reading docs.
  • Honest about difficulty. If a fix needs a developer, say so. Never imply a hard thing is easy.
  • No em-dashes. Use commas, periods, or parentheses.
  • No filler. Cut “it’s important to note that”, “in today’s digital landscape”, and anything else that survives deletion without changing meaning.

​
Vocabulary rules

  • WAIO is always all-caps, always a proper noun. Never “Waio” or “the waio”.
  • Product names are exact: WAIO Engine, WAIO Agent, WAIO Services, WAIO Methodology. Don’t shorten to “the Engine” on first use in a page.
  • AEO, GEO, AI SEO, MCP readiness, AI readiness: spell out on first use per page, e.g. “AEO (Answer Engine Optimization)”.
  • Severity levels are exactly: critical, high, medium. Lowercase in prose.
  • The three audiences are exactly: people, search engines, AI systems.

​
Page structure

  • One audit issue = one page in issues/, filename kebab-case matching the Engine’s issue identifier.
  • Every issue page uses the headings from the issue page template, in order, verbatim: What this means, Why it matters, How to fix it, Learn more.
  • Frontmatter requires title and description. Issue pages ship indexable; only internal pages (this style guide, the issue template) carry noindex: true.
  • Titles are sentence case: “Missing meta description”, not “Missing Meta Description”.

​
Formatting

  • Use Mintlify components sparingly: <Note> for caveats, <Tip> for shortcuts, <Warning> only for things that can break a site, <Tabs> for platform-specific fix steps, <Steps> for ordered procedures.
  • Code goes in code blocks with a language tag, even one-liners.
  • Internal links are relative (/engine/overview). External links are full URLs.
  • External references: prefer MDN, then web.dev, then official platform docs, then W3Schools. Label links with what the reader gets, not the domain name.

​
Before you ship a page

  1. Read it out loud. If you stumble, rewrite.
  2. Check every heading matches the template.
  3. Check every external link resolves.
  4. Confirm the frontmatter has a real title and description (these are what search engines and AI answers display).
  5. Add the page to docs.json navigation, or it won’t appear.