• /
  • Log in
  • Free account

UI paths

Explaining where to find UI pages and elements can be tricky. When done well, path descriptions can make navigating our UI easier for readers.

Read on for tips on writing and formatting a UI path.

Guidelines for writing good UI paths

Our goal for UI paths is to make them easy to use and understand, preferably written in a conversational way. We're not concerned with absolute consistency. The examples here are guidelines and not firm rules.

Guideline

Description

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:

To find details about the entity associated with a span:

  1. From a span’s details pane [link to doc section above], select Attributes.
  2. Look for entity-related attributes, like entityId and entity.name.

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.

Use your best judgment

If you’re ever feeling stuck when writing a UI path, use your best judgment. The best way to format or word a UI path may depend on the path’s length and context.

For example, whether or not to include a URL is up to you. If including Go to one.newrelic.com in a path description is cumbersome or unnatural, exclude it. If it helps orient the reader, feel free to include it. This same thinking applies towards most of our guidelines.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.