Writing UI
A customer interacts with the UI to accomplish a task. The documentation explains the steps and then get out of the way so the customer can accomplish that task.
Style guidance for writing UI and procedures is well-documented in the Google Developer Documentation Style Guide. This style guide does not attempt to reproduce their efforts, which you can consult. Instead, this page documents common topics that occur regularly in writing documentation.
UI guidance
When practical, focus on the task at hand instead of referring to the UI.
You may use > to indicate procedural steps that a user would take in quick succession in the same navigation tool or screen.
One example of this is pointing a mouse over a menu to select an item in that menu. In the following example, the user selects Add a Stage after entering the Query Workbench. The step to select Add a Stage should be a separate step.
- Recommended
-
✅ From the sidebar, navigate to Querying > Query Workbench. Select Add a Stage.
- Not recommended
-
✘ From the sidebar, navigate to Querying > Query Workbench > Add a Stage.
Directional language and locations
Avoid using directional language when possible. However, if avoiding directional language is inconvenient due to explaining UI features, prioritize using directional language over including a screenshot.
- Recommended
-
✅ Click New to add another data source.
- Not recommended
-
✘ Click New in the upper right section to add another data source.
If you must mention location, use relative location instead of absolute location.
- Recommended
-
✅ Click Applications Manager in the sidebar to return to the list of applications.
- Not recommended
-
✘ Click Applications Manager in the top left corner to return to the list of applications.
Windows, screens, pages, and other elements
Use screen to refer to pages within Springboard or Fusion. In general, avoid using window when referring to the Fusion or Springboard UI.
Inconsistent capitalization in the UI
When a term displays as all uppercase in the UI, use sentence case.
If a term displays differently than how we would write it on the documentation site, use the term and style preferred by the Docs team. One example is the situation where the Springboard website uses custom CSS to style certain names in all capital letters, but we do not use all capital letters on the documentation site.
- Exception
-
Use the capitalization listed in the glossary if the term is a product name or traditionally capitalized term.
Resources
Consult the following resources for writing UI and procedures: