Writing about the UI

This topic covers how to write about the UI, the best verbs and prepositions to use, what to call parts of the UI, and how to guide the user through tasks.

• Describe the prop value and tasks, and provide an example.
• Don't describe the UI piece-by-piece. Focus on use cases instead.
• Write steps for actions users can't figure out themselves.
• Keep the average number of steps between five and nine.
• Write with active voice. If you can add “by zombies” at the end, it's likely passive.
• Use bold for component names and match the capitalization as it appears in the UI.
• Use x (italicized) for variable text in UI component names, such as: "Click Select all x rules, and then select Activate."
• Test all procedures before you publish.

Keep these principles in mind when writing about the UI.

Write about use cases. Describe the purpose of the UI and its use case, and provide an example, if possible. If the UI text is doing its job, you shouldn't be writing, "this button does this, this tab shows that."

Eliminate "duh" procedures. Write documentation for complex interactions or when you want to convey content that doesn't fit on the screen. Don't write obvious steps, such as, "Click Save to save your document." Provide in-product assistance to minimize the number of step-by-step instructions and screen captures in the documentation. Both can quickly go out of date.

Keep it focused. Explain one way to accomplish the task and let users discover the alternative. Don't provide extraneous details.

Test your docs as you go. Push all the buttons and ensure that your content reflects real-world scenarios. Put yourself in your users' shoes, and test each step locally. Test your instructions for multiple use cases (and potentially on multiple versions if you plan to backport your changes).

UI icons can be helpful to include when describing a procedure that requires the user to interact with the UI, for example, if they need to click a button or another UI element. Follow these guidelines:

• Use the approved list of EUI icons.
• Include the tooltip text, image, and alt-text for optimal accessibility.
• Avoid using parentheses before and after the UI icon image, which can disrupt screen readers' speech and braille outputs.

Although screenshots can be worth a thousand words, they are also expensive to maintain, especially in an environment with rapid releases.

Screenshots work best in:

• Timebound docs, such as highlights docs and blog posts
• Procedures for a complex UI
• Introductions

The following table can help you decide whether a screenshot is right for your doc.

When taking a screenshot:

• Use a tool like the Window Resizer Chrome extension to set the window's viewport.
  • Set the aspect ratio to 16:9 (1366x768px).
  • If the screenshots are hard to read, set the aspect ratio to 4:3 (1024x768px) instead.
  • Use the same aspect ratio to capture all screenshots on the page.
• Set your zoom level to 100%.
• If you have made any color adjustments, reset to the default on your monitor or select Generic RGB.
• Avoid: drop shadows, jagged edges, and oversized images.
• Include only the essential UI components. The main menu, breadcrumbs, header, toolbar, and search bar often change, so we generally exclude them.
• Add a border around the screenshot to give it definition and ensure it's not "floating" against a white background. Refer to Screenshots for details about the :screenshot: attribute.
• If you need to draw attention to a specific part of the screenshot, you can draw a border or use an annotation, such as an arrow. If you do, keep these in mind:
  • Use Elastic's brand colors for the annotation. We recommend the pink accent color, hex #F04E98.
  • Ensure your annotations are no more than 3px in thickness.

If the screen is very complex, it might help to add callouts:

• Number them; do not use letters.
• Order numbers from left to right, top to bottom.
• Make sure that the callout number is readable in the documentation.
• Provide an explanation for each callout.

In Kibana, there are multiple ways for users to navigate to apps and pages. Depending on the environment and initial setup, users can be served with different navigations where the structure, interactions, and visible features differ.

When referring to apps or pages in the docs, and especially in tasks and tutorials, it's important that you remain as close as possible to the user's truth. For that, use one of the following solution-agnostic patterns:

• The app is directly available in the main menu: Find <APP> in the main menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md).

• The app or page is accessible through only the global search field: To open **APP or PAGE**, find **PARENT** in the main menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md).

You can adapt these patterns and the link to the search bar documentation to match your context and scenario.

Looking for the right word? Here you'll find which words to use when writing about the UI. You can also refer to Word choice and our Accessibility guidelines for specific words and use cases.

Use the language in this table when writing about UI components.

• Don't use the verbs open and/or close when a user interacts with a menu. Use From the menu,... instead.
• Refer to it as "menu." Don't call it a "dropdown menu" or "dropdown list."

• If there is no text next to an actionable, visual symbol, it's an icon.
• If there is text next to an actionable visual symbol, it's a button.
• An actionable piece of text without a visual symbol is either a link or a button.
• In the docs, refer to an icon with its symbol.

In this example, the (...) represents the action menu icon.