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 
SearchEngine.configure do |c|
  c.host = "localhost"
end
Bad 
SearchEngine.configure do |c| c.host = "localhost"; c.port = 8108; end

​
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). 
Related: [Relation](/projects/search-engine-for-typesense/v30.1/relation), [DX](/projects/search-engine-for-typesense/v30.1/dx), [Observability](/projects/search-engine-for-typesense/v30.1/observability)
  • 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 
See [Observability](/projects/search-engine-for-typesense/v30.1/observability).
Bad 
Click [here].

​
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 
# Compiles the schema for a collection.
#
# See docs → Schema → API for the API overview and return shape
# Returns a deeply frozen Typesense-compatible schema (Hash)

​
Reusable snippets

Troubleshooting callout 
> Having trouble? See [Troubleshooting](/projects/search-engine-for-typesense/v30.1/troubleshooting) for fixes.

​
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