Writing standard

Write for browser operators

Operators are comfortable with admin configuration pages. They have ActiveAdmin and Litmos admin access only. They should not need CLI, Git, database access, logs, feature flag tooling, Rails console, or code knowledge to follow a normal runbook.

Style rules

• Use active voice.
• Use second person: “you”.
• Keep sentences short.
• Use sentence case headings.
• Use bold for UI labels.
• Use numbered steps for procedures.
• Include expected results.
• Include escalation criteria.

Required sections for workflow pages

1. When to use this.
2. Before you begin.
3. Steps.
4. Expected result.
5. If this fails.
6. Escalate when.

Screenshot guidance

Use staging screenshots by default. Staging keeps production customer data out of docs while still showing the real Jericho UI.

Every complex browser workflow should eventually have screenshots. Store sanitized screenshots under public/screenshots/ and reference them from the page.

Before adding a screenshot, confirm it uses a staging or synthetic tenant, redacts secrets and personal data, and still shows the exact UI labels the operator needs.