Skip to main content
Use this guide to keep docs consistent, clear, and easy to navigate.
  • Audience: Ruby/Rails engineers integrating the engine
  • Scope: Markdown/MDX only

​
Tone & clarity

  • Be direct and actionable. Prefer examples over abstract prose
  • Avoid jargon; define terms on first use
  • Use short paragraphs and bullet lists; keep lines ≤100 chars
  • Prefer present tense and active voice

​
Headings & anchors

  • Use sentence‑case headings (e.g., “Schema compiler” not “SCHEMA COMPILER”)
  • Keep heading levels consistent within a page
  • Use hyphenated, lower‑case anchors in links
  • Keep section names stable; avoid churn that would break anchors

​
Code fences

  • Always specify a language: ruby, bash, json, yaml, mermaid, text
  • Keep examples minimal and runnable; redact secrets (e.g., ***)
  • Fit lines ≤100 chars; wrap long command outputs with text
Good
Bad

​
Mermaid diagrams

  • Prefer small diagrams (≤ ~15 nodes) with clear labels
  • Use concise titles when helpful
  • Keep labels consistent with section names
Example Add a compact Related block with 2–4 nearby links (use site‑relative links).
  • Prefer descriptive anchors: “See Observability → Logging” instead of “click here”
  • Use site‑relative links; no bare URLs—wrap in backticks or use markdown links
Good
Bad

​
Cross‑referencing with YARDoc

When public APIs are introduced or changed, update docs and YARDoc together. Use @see to link from YARDoc back to the exact docs anchor. Example

​
Reusable snippets

Troubleshooting callout

​
Acceptance criteria snippets

Include the following in acceptance criteria:
  • “All new/edited docs must include related links and cross‑links to Observability/Troubleshooting where relevant.”
  • “Public APIs touched by this ticket must be referenced in docs and YARDoc with @see links back to the relevant docs section.”
Related: Home, Contribution guide