Child pages
  • Help Files 2.9 Styleguide Notes

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 4.0

...

  • In each document the previous version is at the bottom of the document, current work is done at the top.
  • Make use of comments to seek clarification from collaborators.
    • Try not to resolve a comment as it erases the discussion
  • When content is new or changed please color it in red
  • When previous content is removed please DO NOT delete it, mark it as strikethroguh

...

  • US English. We will write this round of documentation in US English. Afterward, the pages can be translated into other languages and styles.
  • Use Active Voice (not passive).
  • Bold the Tool Name in a list of instructions.
    • At this time, we are bolding the precise name of the tool, not the verbs or other terms.
      • e.g. Click Site Info.
    • Do not place quotation marks around the tool name, just bold it.
    • In the future, we can review whether it would be best to bold the central action of a line of instructions, whether it is a tool name or not.
  • Avoid jargon and "techie speak." If an abbreviation is necessary, be sure to open with the human friendly term and place the abbreviation in parentheses first.
    • Good: Enter the web address (URL).
    • Bad: Enter the URL.
  • Click / Check / Select
    • For the most part, you will use "click" as the verb to act on links, tools, menu items, etc. Be consistent. Do not say "click on" -- the preposition is unnecessary.
      • Good: Click Site Info.
      • Bad: Click on Site Info.
      • Bad: Select Site Info.
      • Bad: Choose Site Info.
      • Bad: Check Site Info.
    • If the action involves a checkbox object, the verb is "check."
    • If the action involves a dropdown menu, the verb is "select."
  • Page titles
    • Capitalize the first word of the page title. We're not using "Title Case."
    • Capitalize any proper nouns in the title, but do not capitalize any other words. For the most part, the proper nouns would be tool names, e.g. Site Info, Announcements.
    • Examples:
      • Adding, editing, or deleting an announcement
      • Sorting Gradebook tables
      • Working with HTML pages in Resources
  • As part of a separate process references to WYSIWIG editor page will be replaced with 'rich text editor'