Define the problem

Add a rule when writers repeatedly face the same decision and inconsistency actually matters. A style guide earns adoption by resolving recurring editorial decisions quickly, not by documenting every preference an editor has ever had.

Choose a useful model

Show the preferred form first, then a concise explanation and example. Start with rules that prevent inconsistent terminology, unsafe instructions and expensive review debates, then add guidance when a real pattern recurs.

Build the workflow

Keep the rule easy to scan while placing rationale and exceptions after it. Write rules as decisions with examples and exceptions so contributors can apply them without asking an editor to interpret abstract principles.

Check the result

Automate deterministic rules and keep contextual judgment in human review. Automate only rules a tool can judge reliably; subjective guidance belongs in review, where context can be considered.

Keep it maintainable

Delete obsolete rules so the guide remains a maintained authority rather than an archive of contradictions. Remove obsolete rules and publish change notes for consequential updates so the guide stays an active contract rather than a historical archive.

Applied example

Apply “A style guide people will actually use” to one real page rather than discussing the rule in isolation. Choose a page with enough complexity to expose failure: headings, a table, a note, an example, a term that appears several times, and at least one action the reader must perform. Review the page once as an author and once as a reader who does not know the internal product vocabulary.

Record defects in observable terms:

  • Which structure carries meaning that is not available in plain text?
  • Which term changes meaning or spelling across the page?
  • Which instruction depends on context that is never stated?
  • Which rule would be difficult to check consistently in review?

A standard is useful when it helps two editors make roughly the same decision on the same content. If the rule sounds correct but cannot be demonstrated on a representative page, refine the rule, add an example, or narrow its scope before treating it as policy.

Quick editorial checklist

  • Define the problem. Add a rule when writers repeatedly face the same decision and inconsistency actually matters.
  • Choose a useful model. Show the preferred form first, then a concise explanation and example.
  • Build the workflow. Keep the rule easy to scan while placing rationale and exceptions after it.
  • Check the result. Automate deterministic rules and keep contextual judgment in human review.