Guidance for describing UI elements

When documenting a user interface, put UI element names in bold, and use appropriate nouns and verbs to describe how to interact with them.

UI elements

When referring to any UI element by name, put its name in boldface, using the <b> element. This includes names for buttons, menus, dialogs, windows, list items, or any other feature in the UI that has a visible name.

Put section and page names in bold without capitalisation. e.g. Go to the dates section of the metadata page.

Don’t bold attribute names if they’re not being directly referenced e.g. If the row is a manuscript delivery date, it means the planned manuscript delivery date, which you can set in the contract, either in the terms section and/or in the delivery dates section if you need more nuanced deliverables.

Put data in single quotes. e.g. The title field contains ‘Hobbit’.

Examples

Do: Click on the add new button.

Don’t: Click on the add new button to bring up the page to a new cost estimate.

UI navigation

Show navigation in bold with chevrons.

Do: Go to Format > Form

Page elements

  • Pages are called pages, not screens
  • Pages have sections
  • There is a sidebar and sometimes a local sidebar
  • There may be a scrollspy
  • They have dropdowns, unhyphenated.
  • They have a top and a bottom, not a header or footer