• EnglishEspañol日本語한국어Português
  • Log inStart now

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. We have different options for handling smaller UI paths and longer UI paths.

Guidelines for writing good UI paths

Our goal for UI paths is to make them easy to understand and follow, preferably written in a conversational way. While we're not concerned with absolute consistency, we want the paths to follow general patterns so as to not introduce unnecessary ambiguity for users interacting with the UI.

Guideline

Description

Start most UI paths with go to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities)**.

Almost any path within our primary UI should start with this stock phrase. Avoid other introductory words like from or login to. And remember, UI paths are always in bold. Avoid showing links that skip across multiple navigation nodes in the UI. For example, instead of this:

one.newrelic.com > All capabilities > Traces

Write this:

one.newrelic.com > All capabilities > Traces.

Use a concise, conversational format

A good UI path is short, conversational, and unambiguous. We often use > between the nodes in a path to aid in keeping things brief, but when the UI is confusing you can also use positional words like left navigation or upper-right.

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 user menu, select Account settings, and then select Plan management.

Here's one that links to an earlier section:

...

  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. Write out the UI path associated with the screenshot in a <figcaption>.

Exclude log-in instructions

Assume our readers are logged in. In other words, don’t include log in to New Relic.

Follow these UI pathing examples

The length of the path should influence your approach. A simple three-step navigation can be fully conversational, while a multiple-step procedure may be an ordered list. And for something buried more than three steps deep, consider using the **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > y > z** convention.

Here are some pathing styles in practice, complete with the appropriate bold styling.

Pathing type

Example

You can describe shorter paths in sentence form.

Go to one.newrelic.com > All capabilities and click the Query builder icon to start querying your data.

For multi-step procedures, use an ordered list with full sentences.

To see details for a specific span:

  1. Go to one.newrelic.com > All capabilities > APM & services.

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

  3. Select a span to see its details.

For lengthier paths, simplify by bracing the UI elements with >. Bold everything in the path.

Go to one.newrelic.com > All capabilities > APM & services > (select an app) > Transactions > (select a transaction) > (select a transaction trace) > Trace details

Lengthier paths may end with actions. Bold the part of the UI path braced in >, but unbold the final action. Only use parentheses for actions nested in a longer UI path.

Go to one.newrelic.com > All capabilities > APM & services > (select an app) > Transactions, then select a transaction.

For image captions of any length, brace UI elements in >.

Go to one.newrelic.com > All capabilities > Mobile > (select an app).

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.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.