1. RightAnswers Solution Manager Creating Custom Content Malcolm Hays IT Communications mhays@umr.edu 341-6779

2. RightAnswers Solution Manager 2 Overview Pre-Solution Creation “Thought” Flow Content Creation Technical Style Common Words / Phrases Typographic Convention Misused Words / Phrases Solution Manager Interface Additional Resources

3. RightAnswers Solution Manager 3 Pre-Solution Creation “Thought” Flow 1)Identify possible issue for inclusion in KnowledgeBase Is a KB article necessary? YES: Continue through steps below NO: Find an alternative way to communicate solution to customer (e.g. update and close existing ticket) 2)Identify steps necessary to resolve issue

4. RightAnswers Solution Manager 4 Pre-Solution Creation “Thought” Flow 3)Create the Solution in the KB Solution Manager web application. 4)Send proposed solution to peers for technical review (is it accurate?). Is there a consensus on the proposed solution? YES: Continue through the next step NO: Revise solution or find an alternative way to communicate solution to customer (e.g. update and close existing ticket)

5. RightAnswers Solution Manager 5 Pre-Solution Creation “Thought” Flow 5)Notify KB Solution Manager Publisher of approval Publishers are: Malcolm Hays – mhays Christopher Dew – dewc Casey Cotita – cotitac 6)Solution Manager Publisher changes status from “Draft” to “Published”.

6. RightAnswers Solution Manager 6 Content Creation Needs to be consistent Consistent use of the same terms keeps users from being confused Certain style elements that are unique to Technical documentation Proper use of grammar is also essential

7. RightAnswers Solution Manager 7 Technical Style Brevity is key Steps should be easy to remember, short and to the point. Aim for one or two related actions in an individual step. Watch for commonly misused words or phrases

8. RightAnswers Solution Manager 8 Technical Style (cont.) Common Words and Phrases Button Don’t use it unless it’s needed to avoid confusion. Instead refer to the label on the button. Further do not click “on” items, simply click them: Correct: Click Next. Incorrect: Click the Next button. Click on Next.

9. RightAnswers Solution Manager 9 Technical Style (cont.) Common Words and Phrases Menu Don’t confuse it with a drop-down box. In use, menu names are preceded by the and followed by menu. You Open a menu, and select or click an item from it. Correct: Open the File menu and click Save As. From the Start menu, select Control Panel. Incorrect: Click Start and Control Panel. Click File  Save As.

10. RightAnswers Solution Manager 10 Technical Style (cont.) Common Words and Phrases Type v. Enter You type information into a form, or a data box. The word enter can be confused with use of the enter key, so should be avoided. Correct: Type your username and password in the spaces provided. Type a name for the file in the Name box. Incorrect: Enter your username and password.

11. RightAnswers Solution Manager 11 Technical Style (cont.) Common Words and Phrases Keyboard Keys Keyboard keys are pressed, not clicked. The name of the key is written in all capital letters. Use a plus sign (+) to describe keyboard shortcuts, but not keyboard and mouse combinations. Correct: Press the ENTER to continue. Press CTRL+C to copy the selected text. Hold down the CTRL key and click to select multiple files. Incorrect: Press Enter to continue. Press CTRL-C to copy the text. CTRL+Click to select multiple files

12. RightAnswers Solution Manager 12 Technical Style (cont.) Typographic Conventions Certain typefaces and fonts are used to indicate specific elements when writing documentation. Here is the short list: Bold type is used to identify buttons, menus and other screen icons that are clicked, as well as the names of boxes where data is typed. Italic type is used within text for documentation manuals and book titles, new terminology, emphasis, and words used in the literal sense. The Courier font is used for sample code and code listings, API and language elements (such as function names and class names), filenames, pathnames, directory names, HTML tags, and any text that must be typed on the screen. is used to indicate a variable name or data that you will provide based on the situation.

13. RightAnswers Solution Manager 13 Technical Style (cont.) Misused Words and Phrases A quick list of words and phrases that are commonly used (or misused) in technical documentation: Box – rather than Field, to describe the space on a form into which information is typed. E-mail – E-mail is hyphenated, with a capital ‘E’ if it occurs at the beginning of a sentence, and lower-case ‘e’ in most other cases. Incorrect: Email, email and E-Mail Internet – There is only one, and it is capitalized. Intranet – Anybody can set up their own intranet, so there are many, and it is lower-case (except at the beginning of a sentence.)

14. RightAnswers Solution Manager 14 Technical Style (cont.) Misused Words and Phrases Pointer – Refers to the arrow (or other shape) designating the mouse on the screen, rather than mouse pointer or cursor. University of Missouri-Rolla – There are no spaces around the hyphen between Missouri and Rolla. Web – As a reference to the World Wide Web, it is a proper noun and therefore capitalized. Web site – is two words, as is Web page, Web browser, and other uses. Note that the second word in the pair is not capitalized.

15. RightAnswers Solution Manager 15 Additional Resources Microsoft Manual of Style for Technical Publications, Third Edition ISBN: 0-7356-1746-5 Associated Press (AP) Handbook of Style ISBN: 0-917360-23-0 IT Communications Wiki https://wiki.umr.edu/itcomm/ Malcolm Hays (mhays@umr.edu, x6779)mhays@umr.edu