Skip to content

GUI Documentation

Jump to bottom
mattrowe-opennebula edited this page Oct 8, 2026 · 3 revisions

Today most GUIs will not require a detailed explanation, but following a few simple guidelines in the documentation can save the reader a lot of time by helping them to get things done quickly in the GUI.

When writing instructions or explanations based on a GUI, consider how familiar with the GUI the reader probably is. There will probably be no need for detailed explanations and screenshots if the doc is intended for advanced users, but on the other hand if writing for new users, or if introducing new GUI interfaces, then applying some of the guidelines below can save the reader a lot of time and frustration.

Text Style

Mention GUI elements in bold, e.g.:

Select Storage, then Datastores...

Avoid “click on,” just say “click <item>,” e.g.:

Click Download.

Nested Menus, Hierarchical Elements

When referring to nested menus or any other hierarchical element, such as a pane that includes tabs, mention them from largest to smallest whenever possible. Preferably use -> to create a breadcrumb-like appearance. When using arrows, use the double asterisks at the beginning and end of the list, for example:

Click Storage —> Datastores —> Backups.

Alternatively, without arrows:

Click Storage, then Datastores, then Backups.

Avoid verbosity such as:

Click Backups in the Datastores section of the Storage submenu.

If applicable, don’t hesitate to mention the software component, for example if the previous step involved the CLI and the reader now has to operate on the GUI, be sure to mention the change:

In the Sunstone UI, click Templates, then VM Groups...

Screenshots

A good practice is to include a “wide view” screenshot of a particular GUI area at the beginning of the document or the relevant section within the document. For example, if writing about using the OpenNebula Marketplace via the Sunstone UI, include a screenshot of the main Marketplace page:

OpenNebula Marketplace

This can greatly help the reader to quickly orient themselves even if you don’t provide additional screenshots.

If possible, when introducing a new top-level menu element show the parent menu and the child menu item in the same image:

Left-hand menu

Try to save the reader time by using redundancy when mentioning icons:

  • Mention the icon by name (use the name provided by the tooltip, if available)
  • Indicate where the icon is located in the GUI
  • Include the icon inline in the text
  • Include a screenshot with mouse pointer and tooltip

For example:

Instantiate icon

As mentioned earlier, all this is not necessary if the doc assumes reader familiarity with the GUI.

To insert inline images into the documentation use the < image > Hugo shortcode:

{{< image
  pathDark="/images/quickstart/dark/sunstone_login_page.png"
  path="/images/quickstart/light/sunstone_login_page.png"
  alt="Sunstone login" align="center" width="50%" mb="20px"
>}}

Refer to the images Wiki page for further information on how to use the shortcode.

Diagrams

Request new or updated diagrams for your document as early as possible, to avoid bottlenecks.

Before requesting a new diagram, check if there is a file suitable for your needs that you can reuse. This is the Official List of Diagrams used in the documentation. This list does not include screenshots.

For more details about where to locate an existing file, or place a new one, refer to Config for Displaying Images.

Back to top

Clone this wiki locally