UI paths

Use a concise, conversational format

More often than not, we should keep UI paths short and conversational. For example:

From the top navigation, select APM, select your application, and then click Distributed tracing.

Consider path length

The length of the path should influence your approach. A simple three-step navigation can be fully conversational. A multiple-step procedure may be an ordered list. And for something buried eight steps deep, consider using the x > y > z convention.

Here's an example of a simple navigation:

From one.newrelic.com, click the Query builder icon to start querying your data.

Here's one for a multi-step procedure:

To see details for a specific span:

1. From the top navigation, click APM and then choose your application.

2. Click Distributed tracing and select a trace from the trace index.

3. Select a span to see its details.

   Here's one for a lengthier path, though this can usually be avoided by following our other guidelines:

   Go to one.newrelic.com > APM > (select an app) > Transactions > (select a transaction) > (select a transaction trace) > Trace details:

Avoid redundancy

If there’s an existing doc or doc section that explains how to get to a specific UI element, section, or page, link to it.

Here's an example that links to an existing doc:

From the account dropdown, select Account settings, and then select Plan management.

Here's one that links to an earlier section:

Orient the reader

If something's hard to locate, you can use terms like top of the screen or left navigation. For example:

From the top navigation, click APM and then choose your application.

Use natural verbs

Use natural, actionable verbs. Think about the user and the logic of the action and then read your steps out loud before deciding.

• Examples: click, select, choose.

Use screenshots

Screenshots can help ground the reader. For instance, if the UI contains a dashboard with multiple options, a screenshot can orient the reader with a common set of procedures.

Exclude log-in instructions

We should assume our readers are logged in. In other words, don’t include log in to New Relic instructions.