Writing Tips for Installation Guides
If you can't consult a full style guide, review these tips to significantly improve your content.
Use active voice
Avoid passive voice (to be verb + past-tense verb). To make your text more dynamic, clear, and (often) shorter, try to use actors and active voice wherever possible.
| Preferred | Discouraged |
|---|---|
| Once you add the required configuration, Auth0 will process all logins for your tenant using this Rule. Before you activate the integration in production, make sure you have configured all components correctly and verified on a test tenant. | Once the required configuration is added, all logins for your tenant will be processed by this Rule. Please make sure all components have been configured correctly and verified on a test tenant before activating the integration in production. |
Make link titles scannable
When you link to other resources, make sure the link describes the action or task in the document to which the link is pointing. Generic link text reduces scannability by forcing readers to read all of the text surrounding a link to identify what to select.
| Preferred | Discouraged |
|---|---|
| You can use the Auth0 Dashboard or the Management API to customize text for the new Universal Login experience. | Click here. |
| To learn how to assign roles to members of organizations, read Add Roles to Organization Members. | You can go to this link. |
Write device-agnostic directions
Remember that user interfaces display differently on different devices. Also, remember that users may be using adaptive devices to view your content.
| Preferred | Discouraged |
|---|---|
| Select Create. | Click Create. |
| Switch to the Applications view. | Switch to the Applications tab. |
| Locate Client Secret. | Scroll up to Client Secret. |
Use verbs and noun/adjectives properly
Be careful about words that can be used as both verbs and nouns or adjectives. Verb forms usually require a space between words, while nouns and adjectives can be compounded.
| Preferred | Discouraged |
|---|---|
| Log in to your account. | Login to your account. |
| Auth0 processes logins. | Auth0 processes log ins. |
| Set up your hardware. | Setup your hardware. |
| Describe your hardware setup. | Describe your hardware set up. |
Use sentence case for headings
Only capitalize the first word and any other proper nouns or Auth0 product names.
| Preferred | Discouraged |
|---|---|
| Add a dependency | Add a Dependency |
| Validate resumed login | Validate Resumed Login |
| Create an Action | Create an action |
Use simple tense for headings
Avoid unnecessary wordiness by using simple tenses for headings.
| Preferred | Discouraged |
|---|---|
| Assign and change users | Assigning and changing users |
| Connect a custom database | How to connect a custom database |
Write steps concisely
When writing introductory text for steps, be direct and concise. Remember that users already know what they need to do with a numbered list of steps.
| Preferred | Discouraged |
|---|---|
| To install the SDK: | Follow the steps below: |
Set user expectations in steps
Tell users what the outcome of their behavior should be before describing the behavior they need to take.
| Preferred | Discouraged |
|---|---|
| To activate this integration, select Save Changes. | Select Save Changes to activate this integration. |
List actions within steps in order
Within individual steps, tell the user what to do in the order they need to do it.
| Preferred | Discouraged |
|---|---|
| Locate the Integrations section, and select Add Integration. | Select Add Integration under the Integrations section. |
Use notes and warning appropriately
Notes and warnings have different functions. Notes should include general information that would be nice to know, whereas warnings contain information that may cause failure if not followed.
If information warrants being presented as a warning, you should include the warning exactly where the user would need to perform the related action. Users should not have to hunt for warnings.