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.
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.
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
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:
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:
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.
Exclude log-in instructions
We should assume our readers are logged in. In other words, don’t include
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.