This topic outlines some guidelines for writing documentation.
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 in a field.
Do not
- Use quotes to highlight UI elements.
- Belabor directions. "Click the Save button to save." can be replaced with "Click Save."
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 when available and also button labels such as (Admin)
Admin Menus
Do
- Give directions based on the broadest audience - i.e. for the "least permissioned" user who can do the action.
- Give instructions only applicable to admins based on the top right (Admin) menu.
- When giving directions to a resource like the schema browser that non-developers can see, use (Admin) > Go To Module > Query instead of (Admin) > Developer Links > Schema Browser which is only available to platform developers.
- 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.
Choosing Page Titles and Headings
Do
- Use active voice. Let's do something in this topic!
Avoid
- -ing. It makes titles longer, it's passive and it's boring.
- Yes, you may have to mix noun phrases (Field Editor) 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.
Consistently capitalize or camelCase phrases within sections. For example, capitalizing Sample Type is common to distinguish this two word phrase as describing a single entity.
AvoidVarying 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, first check the source code to make sure the page is not linked through context-sensitive help. Then check the Backlinks query before during and after the change to make sure you fix every reference.
See Also
Resources
