Variables
Use variables when you need to insert a calculated value or result of a query into a sentence that's easy to read. The guidance is the same whether you call these fill-ins, replacements, substitutions, or any other term.
What's a variable? The bold items below.
| In the code | In the UI |
|---|---|
| We detected anomalous behavior in [service name]. | We detected anomalous behavior in RPM-UI-production. |
| [% of crashes] of crashes share the operating system [operating system type]. | 80% of crashes share the operating system iOS 11.1.2. |
Basics
If the inserted value will be short, place it into the most logical spot in the sentence to make it sound natural. If the value will be long, not readable, or otherwise out of our control, then place it at the end of the sentence. If the variable could be any part of speech or sometimes singular and sometimes plural, separate it by a colon or place it on another line.
| Do | Don't |
|---|---|
| We detected anomalous behavior in bob-long-name-32-october-service-legacy-system. | The service bob-long-name-32-october-service-legacy-system has anomalous behavior. |
| 80% of crashes share the user name pdiddybigdog. | 80% of crashes share the pdiddybigdog user name. |
| Services with multiple errors: 1 | 1 services have multiple errors. |
Placeholder text
For placeholder text in input fields, use “Example: …” And in places like documentation where we’re adding examples inline, use "such as," For example, "X requires an action to be dismissed (such as, confirming a user wants to delete a dashboard).”
