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 | Almost any path within our primary UI should start with this stock phrase. Avoid other introductory words like 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 |
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: ...
|
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.
|
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 |
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 > 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:
|
For lengthier paths, simplify by bracing the UI elements with | 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 | 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.