docs
docs copied to clipboard
Style guide: add guidelines for documenting GUIs
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.
@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.