New: thola v1 is live. Read the launch post →
Docs
thola docs — voice & style guide

thola docs — voice & style guide

Internal reference, hidden from the public sidebar. Useful when you write a new doc or blog post.

The mental model

thola docs follow the "agents, not dashboards" framing established in the original UnifiedGo User Guide. The canonical line:

thola is not a dashboard. It is a team of autonomous AI agents that work alongside you.

Every doc should be readable with that framing in mind.

Voice

  • Confident, not arrogant. "Open Settings → Members" beats "you might want to consider opening..."
  • Mentor-like. Speak to the reader as a peer. Not condescending.
  • Operational. Tell them what to do, what to expect, what could go wrong.
  • Honest about gaps. If a feature is "work in progress on the frontend," say so.

Structure conventions

Most user-guide pages follow this shape:

  1. What it is — one paragraph, plain language
  2. What you can do — bullet list of capabilities
  3. How it works — the procedural detail
  4. Common questions — 3–5 FAQs at the end

For agent-facing pages, add a "Talking to [agent]" table showing example prompts.

The "You say / Agent thinks / Result" pattern

When showing an agent interaction, use:

- You say: "..."
- Agent thinks: "..."
- Result: "..."

The Planner is always the one thinking; the specialist agent is named in the Result.

Section headings

Recurring headings to reuse:

  • What it tracks
  • What data the [X] agent needs
  • How the [X] score is calculated
  • Talking to the [X] agent
  • Common questions

Tables vs prose

  • Use tables for parallel comparisons (metric → meaning, severity → trigger)
  • Use prose for explaining why
  • Avoid 1-column "tables" — they're really just lists

Backticks

Use backticks for:

  • Exact UI labels: Settings → Workspace → Members
  • Status values: pending, paused, completed
  • Field names in tables

Don't backtick general nouns. "The Planner is the orchestrator" not "The Planner is the orchestrator."

Severity colours (consistent across product + docs)

  • 🔴 High — red
  • 🟡 Medium — amber
  • 🟢 Low — green

For score bands:

  • 🟢 Excellent
  • Lime Strong
  • Amber Mixed
  • Orange Strained
  • Red Critical

Image conventions

  • Use the <Figure> component for all diagrams
  • Reference SVGs from /img/...
  • Each illustration should have a caption when context isn't obvious

Blog vs user-guide voice

  • User guide — present tense, procedural ("Open Settings → Members and click Invite")
  • Blog — slightly looser, first-person plural OK ("We built X because..."), past tense for stories

Both should keep a confident, ungrandiose register.

Things not to do

  • No emojis except severity colours and module icons
  • No "AI-powered" or "revolutionary"
  • No marketing copy in user-guide pages
  • No assuming the reader knows what RBAC means (link to it)
  • No long unbroken prose — break with tables, lists, callouts every 4–6 paragraphs
Coupons & promotions