docs icon indicating copy to clipboard operation
docs copied to clipboard

Style guide: add guidelines for documenting GUIs

Open andrew-walford-prisma opened this issue 2 years ago • 1 comments

Some things we probably want to cover in the GUI guidelines:

  • When we want the user to activate a GUI element, do we say select or click?
    • Where we do use “click” (e.g. we might still say “right-click” even if we go with “select” for regular clicks)
    • If we go with"click", IMO we should have a guideline not to say “click on”
  • What font formatting do we need for GUI element names?
  • What terms should we use for GUI elements? (Menus, menu commands, buttons, checkboxes, etc.)
    • When should we explicitly use these terms, and when should we avoid them? For example, some style guides state never to say “Click the X button”, but to state “Click X”.
  • Screen, page, window, tab - which term to use for screens in the UI?
  • If a GUI element has an OK button to apply user changes, at the end of a procedure do we include a step to click this button? Some style guides say omit this step, others say include it. I'd vote to omit it, because our users are technically literate, and it keeps the docs shorter.

andrew-walford-prisma avatar Aug 30 '22 15:08 andrew-walford-prisma

@zachtil I've assigned this to you but there's no hurry on this task. If you'd prefer to take your name off it until you get time to do it, then feel free to do so.

andrew-walford-prisma avatar Sep 01 '22 09:09 andrew-walford-prisma