Voice & tone
Rook talks like a good engineer at the next desk: exact about the numbers, plain about what happened, and calm when something breaks.
Attributes
Four words to check copy and design against. If a sentence or a screen fails one of them, rewrite it before you polish it.
Exact
Name the real thing: the sheet number, the version, the file size.
- Copy
- “Rook Lateral 2.3.1, 103.4 MB”, not “the latest version”.
- Design
- Tabular figures for values; show units and scale beside the number.
Plain
Short words, active verbs, one idea per sentence. No marketing.
- Copy
- “Send from Revit adds the detail to your library”, not “seamlessly sync your workflow”.
- Design
- Ruled lists over boxes. One label per control; no decoration that says nothing.
Calm
State what happened without alarm or cheer. No exclamation marks.
- Copy
- “The import stopped at family 14 of 32”, not “Oops! Something went wrong”.
- Design
- Red only for failure. Errors sit next to the thing that failed, not in a modal.
Useful
Every message ends with what to do next, or says that nothing is needed.
- Copy
- “Ask an organization admin to add a seat”, not “Access denied”.
- Design
- Put the next action in the message itself: a button, a link, or the setting.
Tone by context
The voice stays the same everywhere; the tone moves with the reader's situation. Someone reading an error is in a different place from someone browsing the docs.
| Context | Tone | Example |
|---|---|---|
| Docs | Instructive, step by step. Second person, present tense. | In Revit, select the view and choose Send from Revit. The detail appears in the Rook Library within a minute. |
| Release notes | Factual and brief. Lead with what changed for the engineer, not the code. | Rook Lateral 2.3.1 · Wind loads now follow ASCE 7-22 by default. Existing models keep their code until you change it. |
| Errors | Calm and specific. What failed, why, what to do. Never blame the user. | Couldn’t read Beam to column connection.rfa. The file was saved in Revit 2027; the add-in supports 2023–2026. |
| Empty states | Brief and inviting. Say what will appear here and how to add the first one. | No families yet. Send a family from Revit, or import a folder of .rfa files. |
| Portal & licensing | Precise and neutral. Numbers, dates and who can act. No upsell. | 4 of 5 seats in use. Seats renew on Jan 14, 2027. Only organization admins can add seats. |
Words to use and avoid
Use the words engineers use for the thing. Avoid words that sell, hedge or blame.
| Use | Because |
|---|---|
| detail, family, project | The Library’s nouns, as Revit uses them. |
| sign in, sign out | Same verbs on the site, Portal and add-in. |
| organization member | Matches the Portal; admins are members too. |
| failed, stopped | Say what happened. Pair it with the reason. |
| Send from Revit | The feature name, in title case, always in full. |
| Avoid | Write instead |
|---|---|
| assets, content | The thing itself: detail, family, project. |
| log in, login | Sign in. |
| seamless, powerful | What it does, with a number if you have one. |
| oops, uh-oh | What failed and why, in one sentence. |
| simply, just | Nothing. Drop the word; the step stays. |
A rewrite
An import error from the Rook Library, before and after. The rewrite says what failed, why, and what to do next, in fewer words.
Before
Oops! Something went wrong.
We couldn’t import your content. Please try again later or contact support.
- Cheerful about a failure, and vague about which file.
- “Try again later” will fail the same way.
After
Import stopped at family 14 of 32
Beam to column connection.rfa was saved in Revit 2027. Save it in Revit 2026 or earlier, then retry.
- Names the file and the point it stopped.
- Gives the cause and the fix in one sentence.
- The next action is a button in the message.
Mechanics
The small rules that keep every page consistent. When in doubt, match what a structural drawing would print.
| Topic | Rule | Write |
|---|---|---|
| Sentence case | Titles, buttons, tabs and labels. Capitals only for proper nouns and product names. | Import families · Send from Revit |
| Numbers | Numerals for every count and measure, with tabular figures where values line up in a column. | 3 details · 14 of 32 · 103.4 MB |
| Units & scale | Feet and inches with ' and ", no spaces inside the value. Metric with a space before the unit. Scale exactly as printed on the sheet. | 3" = 1'-0" · 12'-6" · 150 mm |
| Dates & time | Month abbreviated, no ordinals. ISO dates in file names and logs. Relative time only under a day. | Oct 6, 2026 · 2026-10-06 · 12 min ago |
| Versions | Product name, then the number. No “v” in prose; keep it in tags and file names. | Rook Lateral 2.3.1 · Revit 2023–2026 |
| Punctuation | No exclamation marks. Curly quotes, en dash for ranges, a middle dot to join facts on one line. | S-600 · 3" = 1'-0" · Approved |