See Also
References to UI Elements
Do
- Use bold for UI elements, such as button names, page titles and links.
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 not
- Use quotes to highlight UI elements.
Do
- Describe series of clicks by order of execution.
- Good: "Select Export -> Script"
- Bad: "Select Script from the Export menu."
Admin Menus
Do
- Give directions based on the top right Admin drop-down
Do not
- Give directions based on options in the left nav bar. Never assume that the left nav bar is visible to anyone.
-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.
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 create a wiki page
- Creating 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.
Resources
