See Also
References to UI Elements
Do
- Use bold for UI elements, such as button names, page titles, and links.
- Usually use bold for menu options the user should choose.
- Use quotes for something the user should type or see entered.
Do not
- Use quotes to highlight UI elements.
Except
- When the use of bold would be confusing or overwhelming.
- For example, if you have subheadings that use bold and very little text beside UI element names, too much text would be bold. In such a case you might use quotations around UI element names, as an exception.
Do
- Describe series of clicks by order of execution using ">" progressions into menus.
- Good: "Select Export > Script"
- Bad: "Select Script from the Export menu."
- Include both icons and button labels such as (Admin)
Admin Menus
Do
- Give directions only applicable to admins based on the top right (Admin) drop-down
- Give directions applicable to non-admins as well, such as editors, coordinators, study managers, based on options all these users will have in the UI, such as the Manage tab instead of (Admin) > Manage Study.
Do not
- Give directions based on options in the left nav bar. It went away years ago.
-ing Words in Headings
Do
- Use active voice. Let's do something in this topic!
Avoid
- -ing. It makes titles longer (the TOC is space constrained on width), it's passive and it's boring.
- Yes, you may have to mix noun phrases (Field Properties) and imperatives (Create a Dataset) in a TOC section. Still, it's usually possible to keep subsections internally consistent.
Parallelism
DoUse the same verb form (e.g., participles, imperatives or infinitives) consistently in bullets and titles.
Consistently use either verb or nouns statements in bullets and section titles.
Generally, prefer active verb phrases ("Create XYZ") over noun statements or participles.
Consistently punctuate lists.
AvoidVary the use of verbs and nouns in sections. For example, a section should not have all three of the following forms used - better is to keep all bullets parallel and use the active form that appears in the first bullet for the others.
- Create a wiki page
- How to edit a wiki page
- Printing a wiki page
If You Move a Page...
- Update all related on-page TOCs, both in the section where the page came from and in the section where the page went to.
- If you do not do this, it is nearly impossible to track down that something is missing from an on-page TOC without going through every TOC item one-by-one.
- Ensure that the page title uses wording parallel to the other titles in its new node.
- For example, if a verb ("Do this") title moves into a section where all the pages are noun titles, you need to fix things so that the pages titles are all nouns or all verbs.
- There can be exceptions, but in general, titles should be parallel at the level of a node.
If you Rename a Page...
- Consider not doing that. What are the alternatives. Can you wrap the old page in the new name? Downsides of renaming pages are both broken links and lost history.
- If you have to, check the Backlinks query before during and after the change to make sure you fix every reference.
Resources
