Add UI content guidelines to Contributor Guide¶

Problem description¶

The OpenStack UX project is interested in adding a section to the OpenStack Documentation Contributor Guide that provides guidance on maintaining consistent structure, style, and syntax for any graphical user interfaces (GUI) developed by the OpenStack project teams. The guide could be applied to IA efforts for the panel headings, modal headings, modal section headings, section descriptions, labels, etc.

The value of this effort is to help provide an improved usability for operators, admins and end users.

Proposed change¶

Add a section to address UI content guidelines. This UI content guidelines section could be added as a peer to the Writing Style section within the OpenStack Documentation Contributor Guide. Proposed table of contents:

• Value/Intro
• Capitalization guidelines for text in UI
  • Examples of sentence-style capitalization
  • Examples of headline-style capitalization
  • Common UI elements/headings that use sentence-style capitalization
  • Common UI elements/headings that use headline-style capitalization
  • UA Cheat Sheet (visually show style in an image)
• Common action labels (i.e. Cancel, Add, Close, Delete, etc…), other common labels (i.e. IP address)
• Refer to user interface elements consistently (link to ui-terminology.html)
• Follow writing style guidelines (link to page in contributor guide)
• Error message guidelines (structure, clarity, completeness)
  • Structure definitions
  • Examples

Implementation¶

Dependencies¶

This work is a collaboration between the UX and Doc team that requires input from both projects.

Testing¶

Testing will follow the standard documentation review process.

References¶

• Discussion can occur using any official medium including IRC in #openstack-doc, the openstack-docs mailing list with [ui-content-guidelines] in the subject.