Skip to main content

Documentation Standards

This page explains the maintenance standard we use for keeping service docs aligned with current product behavior.

The goal is simple:

  • plain-language docs outside technical/
  • product-grounded technical docs inside technical/
  • current product behavior wins when older copy and current behavior disagree

Update Order​

Use this order every time:

  1. Review one surface at a time.
  2. Confirm the current product flow, labels, limits, and outcomes.
  3. Update the plain-language doc for that surface.
  4. Update the technical doc for that surface.
  5. Build the docs site.
  6. Fix wording, links, or broken pages before stopping.

Writing Rules​

Outside technical/​

Use plain language.

  • aim for short sentences
  • explain terms before using them
  • prefer examples over jargon
  • write for a smart reader who is new to the product

Inside technical/​

Be specific without becoming unreadable.

  • name current states and modes
  • explain flows in the same order users encounter them
  • call out important limits and distinctions
  • avoid pretending future work already exists

Coverage Areas​

These standards matter most for:

  • Notary web UI
  • Notary desktop
  • Ghostwriting
  • Editorial
  • Translation
  • Convert
  • Analytics

Good Review Questions​

Ask these every pass:

  • Does the doc match the actual UI labels?
  • Does it describe the real steps in the current flow?
  • Does it mention limits that still exist in the product?
  • Does it say "can" when the product really means "does"?
  • Does it explain what is local, what is cloud, and what is optional?

Exit Criteria​

A surface is in good shape when:

  • its plain-language doc exists
  • its technical doc exists
  • the docs reflect current product behavior
  • the docs build passes