Guiding Principles

• Focus on the end-user
• Keep language and instruction easy, clear, and accurate
• Make documents human-friendly

Style

The Help Files to date have been edited by Indiana University using their technical writing style guide (https://kb.iu.edu/data/apff.html). When in doubt, use the Chicago Manual of Style for additional guidance.

Quick Notes

Google Docs Editing Process

• 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

Style

• 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'