RightAnswers Solution Manager Creating Custom Content

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

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

3. Pre-Solution Creation“Thought” Flow • 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) • Identify steps necessary to resolve issue RightAnswers Solution Manager

4. Pre-Solution Creation“Thought” Flow • Create the Solution in the KB Solution Manager web application. • 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) RightAnswers Solution Manager

5. Pre-Solution Creation“Thought” Flow • Notify KB Solution Manager Publisher of approval • Publishers are: • Malcolm Hays – mhays • Christopher Dew – dewc • Casey Cotita – cotitac • Solution Manager Publisher changes status from “Draft” to “Published”. 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 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 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. 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. 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. 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 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. • <Courier Italic in angle-brackets> is used to indicate a variable name or data that you will provide based on the situation. 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.) 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. 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) RightAnswers Solution Manager