Skip to main content

​
Tone and voice

Write in a technical, straight-to-the-point, and concise style while remaining approachable. Prioritize clarity over formality.
  • Use active voice and second person (“you”)
  • Keep sentences short — one idea per sentence
  • Lead with the goal, then provide instructions
  • Avoid unnecessary filler words
  • No hedging — be confident and direct
  • No marketing language — docs inform, they don’t sell

​
Voice attributes

Primo’s documentation voice is always clear, confident, structured, action-oriented, and professional.
AttributeMeansDoes NOT mean
ClearPlain language, one idea per sentence, no ambiguityDumbed down or patronizing
ConfidentDirect statements, no hedging or apologizingArrogant or pushy
StructuredOrganized, scannable, logicalRigid or robotic
Action-orientedGuides the user toward what to do nextCommanding or aggressive
ProfessionalRespects IT expertise, uses correct terminologyStuffed with corporate jargon

​
Tone settings

Help center articles use medium formality, medium energy, and high technical depth. Write professionally but conversationally, at a steady pace, and use technical terminology freely — readers are IT professionals.

​
Language conventions

​
Terminology

Always use exact terms from the glossary. Never substitute synonyms for glossary terms.
UseAvoid
HR systemHRIS
the dashboardin Primo, to Primo
device managementMDM (on first use, spell out)
devicemachine, computer
enrollregister, add
zero-touch deploymentautomatic setup
onboarding / offboardingad hoc alternatives

​
Product references

Minimize mentions of “in Primo” or “to Primo.” Only include the product name when:
  • Distinguishing Primo from another system
  • First mention in a document
  • The context would be unclear without it
Avoid: “Navigate to Primo and click Settings”
Prefer: “Navigate to Settings” Avoid: “Import employees to Primo”
Prefer: “Import employees”

​
Acronyms

Spell out acronyms on first use, followed by the abbreviation in parentheses. Use the abbreviation for subsequent mentions. Example: Mobile Device Management (MDM) enables remote configuration. MDM policies control device settings.

​
Style conventions

​
Headings

  • Use sentence case: “Set up your account” not “Set Up Your Account”
  • Use imperative verbs: “Configure SSO” not “Configuring SSO”
  • Keep headings concise and action-oriented
AvoidPrefer
Configuring your settingsConfigure settings
Managing employee devicesManage devices
Understanding zero-touchUnderstand zero-touch
Importing via CSVImport via CSV

​
Formatting

  • Bold for UI elements: Click Settings > Integrations
  • Watch for stray ** — bold markers that were not properly closed or that leaked from a previous span. A line should always have an even number of ** markers. Common patterns to catch:
    • ***word** (extra leading *) → **word**
    • **word **other** (nested open marker) → **word other**
  • Code formatting for:
    • File names: config.json
    • Commands: mint dev
    • Paths: /api/employees
    • Code references: deviceId
  • Use <Steps> for sequential steps — prefer this over numbered lists whenever steps follow a defined order
  • In <Step title="..."> attributes, do not use markdown formatting — bold (**) and links ([text](url)) render as literal characters in JSX attributes. Plain text only in titles; use the step body for rich content if needed
  • Use bullet points for non-sequential items
<Steps>
  <Step title="Navigate to Settings > Team">
  </Step>
  <Step title="Click 'Add member'">
  </Step>
  <Step title="Enter one or multiple email address(es) and choose a role">
    To invite multiple members at the same time, you can specify multiple
    emails separated with commas in the 'Email' field.
  </Step>
</Steps>

​
Article structure

Follow a consistent pattern across articles:
  1. Title — Imperative verb + object (e.g., “Connect your HR system”)
  2. Description — One-sentence summary of what the reader will accomplish
  3. Prerequisites — List requirements before starting (if applicable)
  4. Steps — Numbered instructions with clear actions
  5. Next steps — Link to related content (if applicable)

​
Card groups

Use <CardGroup> to display related links as visual cards. Follow these guidelines:
  • Maximum 3 cards per row — Use cols={3} or fewer for readability
  • Keep card copy in sync — Card titles and descriptions must match the referenced article’s frontmatter
  • Use cards for collections — Best for overview pages linking to related content
<CardGroup cols={3}>
  <Card title="Connect your HR system" icon="users" href="/employees/connect-hris">
    Sync employee data automatically from your HR system.
  </Card>
  <Card title="Import via CSV" icon="file-csv" href="/employees/import-via-csv">
    Bulk import employees using a spreadsheet.
  </Card>
  <Card title="Automate onboardings" icon="wand-magic-sparkles" href="/employees/automate-onboardings">
    Set up automatic device provisioning for new hires.
  </Card>
</CardGroup>
Maintenance: When updating an article’s title or description, search for any cards referencing that page and update them to match.

​
Quick reference

ElementConventionExample
HeadingsSentence case, imperative”Configure disk encryption”
UI elementsBoldClick Save
Code/commandsBackticksRun mint dev
Product nameMinimize usageOmit “in Primo” when obvious
AcronymsSpell out first use”HR system” not “HRIS”
Card groupsMax 3 columns, synced copy<CardGroup cols={3}>
Sequential stepsUse <Steps> component<Steps><Step title="...">