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.
Start most UI paths with
Almost any path within our primary UI should start with this stock phrase. Avoid other introductory words like
Use a concise, conversational format
A good UI path is short, conversational, and unambiguous. We often use
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:
To find details about the entity associated with a span:
Orient the reader
If something's hard to locate, you can use terms like
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.
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
Exclude log-in instructions
Assume our readers are logged in. In other words, don’t include
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](https://one.newrelic.com/all-capabilities) > y > z** convention.
Here are some pathing styles in practice, complete with the appropriate bold styling.
You can describe shorter paths in sentence form.
Go to one.newrelic.com 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:
For lengthier paths, simplify by bracing the UI elements with
Go to one.newrelic.com > 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
Go to one.newrelic.com > 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 > 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.