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 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.

Customize