Manual Styles for Technical Publications -- Rajesh Singamsetty

1. Style Guides Course code - CMTEU - 003

2. What is a Style Guide? A style guide or style manual is a set of standards for the writing and design of documents, either for general use or for a specific publication, organization or field. The implementation of a style guide provides uniformity in style and formatting of a document. Commit Internal Training Session- Course code CMTED -003 2

3. Commit Internal Training Session- Course code CMTED -003 3

4. Why Style Guides? Time Saving Cost Saving Consistency Professionalism Commit Internal Training Session- Course code CMTED -003 4

5. Topics in MSTP Document user interface Content Formatting and Layout Global Content Content for Software Developers Web Content Indexing and Attributing Tone and Rhetoric Commit Internal Training Session- Course code CMTED -003 5

6. Document user interface Screen Terminology Dialog Boxes and Property Sheets Menus and Commands Mouse Terminology Messages Key Names Command Syntax Commit Internal Training Session- Course code CMTED -003 6

7. Commit Internal Training Session- Course code CMTED -003 Icon Open window Start menu Start menu Desktop Notification area Taskbar Quick Launch bar 7

8. Commit Internal Training Session- Course code CMTED -003 8 Dialog Box Properties Sheet

9. Commit Internal Training Session- Course code CMTED -003 9 Menus and Commands

10. Dialog Boxes And Property Sheets Commit Internal Training Session- Course code CMTED -003 10 Square box that is selected or cleared to turn on or off an option. More than one check box can be selected. Check box Text box with a list box attached. The list is always visible. Because users can either type or select their choice, you can use enter to describe the action. Follow your project style sheet. Combo box Rectangular button that initiates an action. A command button label ending with ellipses indicates that another dialog box will appear: More information is needed before the action can be completed. Command button

11. Dialog Boxes And Property Sheets Commit Internal Training Session- Course code CMTED -003 11 Arrow associated with a drop-down combo or list box or some toolbar buttons, indicating a list the user can view by clicking the arrow. Drop-down arrow Closed version of a combo box with an arrow next to it. Clicking the arrow opens the list. Drop-down combo box Closed version of a list box with an arrow next to it. Clicking the arrow opens the list. Depending on the type of list, use either list or box, whichever is Clearer. Drop-down list box

12. Dialog Boxes And Property Sheets Commit Internal Training Session- Course code CMTED -003 12 Frame or box that encloses a set of related options. In Windows XP, a group box can be indicated by a single line that unifies the options below it. The group box is a visual device only. Group box Label (do not use caption) Text attached to any option, box, command, and so On. Any type of box containing a list of items the user can select. The user cannot type a selection in a list box. List box

13. Dialog Boxes And Property Sheets Commit Internal Training Session- Course code CMTED -003 13 Round button used to select one of a group of mutually exclusive options. Option button (avoid radio button) Indicator on a gauge that displays and sets a value from a continuous range, such as speed, brightness, or volume. Slider Text box with up and down arrows that the user clicks to move through a set of fixed values. The user can also type a valid value in the box. Spin box

14. Dialog Boxes And Property Sheets Commit Internal Training Session- Course code CMTED -003 14 Tab On the Tools menu, click Options, and then click the View tab. Title of the dialog box. It usually, but not always, matches the title of the command name. Text box Command button with two “greater than” signs (>>) that enlarges a secondary window to reveal more options or information. Unfold button If you refer to unnamed buttons that appear in the interface, use the syntax as Unnamed buttons

15. Menus and Commands Commit Internal Training Session- Course code CMTED -003 15 Menus contain commands. Dialog boxes contain command buttons and options. Do not refer to a command as a menu item. Users click menu items. If you must refer to the user action of opening a menu, use click. Example - On the File menu, click Open. On the View menu, point to Toolbars, and then click Formatting. Refer to unavailable commands and options as unavailable, not as dimmed, disabled, or greyed. Example - There are several unavailable commands on the Edit menu.

16. Commit Internal Training Session- Course code CMTED -003 16 Mouse Terminology Do not use cursor or mouse cursor to refer to the pointer. Use pointer or mouse pointer instead. Use click, not click on. Example - Using the mouse, click the Minimize button. However use in to refer to clicking in a general area within a window or dialog box, not click the window or click the Styles box. Example – Click in the window to make it active. Use drag, not click and drag Use drag, not drag and drop Always hyphenate double-click and right-click as verbs

17. Commit Internal Training Session- Course code CMTED -003 17 Messages • Avoid vague wording, eg: unexpected error. • Avoid “please.” It can be interpreted to mean that a required action is optional. • Avoid uppercase text and exclamation points.

18. Commit Internal Training Session- Course code CMTED -003 18 Command Syntax

19. Content Formatting and Layout Art, Captions, and Callouts Cross References Heading and Subheadings Line Breaks Page Breaks Tables Notes and Tips Commit Internal Training Session- Course code CMTED -003 19

20. Global Art Commit Internal Training Session- Course code CMTED -003 20 I am an African equids best known for my distinctive stripes. My stripes come in different patterns unique to each individual. We are generally social animals who live in small harems to large herds. I am a close relative to donkey.

21. Cross Reference Try to write and edit so that you use cross-references only for material that is not essential to the task at hand. For example, users should not have to look up material to complete a procedure. Commit Internal Training Session- Course code CMTED -003 21

22. Document Conventions Consistent text formatting helps users locate and interpret information easily. Commit Internal Training Session- Course code CMTED -003 22

23. Headings and Subheadings Commit Internal Training Session- Course code CMTED -003 23 Heading style varies among groups. The guidelines in this section are widely used and can make it easier to share files across groups. If your group follows a different practice, however, use your group’s style consistently. Group C Getting Started with Visio Group B About Visio Group A Introduction to Visio

24. Line Breaks Commit Internal Training Session- Course code CMTED -003 24 Avoid very short lines that leaves large amounts of white space at the end of a line. Do not break a word if it leaves a single letter at the end of the line. Do not break a word if it leaves fewer than three letters at the beginning of the next line. Do not end a page with the first part of a hyphenated word. Do not hyphenate the product names. Try to keep the heading in one line. avoid breaking function names and parameters.

25. Lists Depending on the type of material that you have to present, you can choose among several types of lists: bulleted, numbered, unnumbered single-column, unnumbered multicolumn, or a “term list.” Commit Internal Training Session- Course code CMTED -003 25 To log on to a database 1. On the File menu, click Open Database. 2. In User Name, type your name. 3. In Password, type your password, and then click OK. • Reports • Forms • Tables • Modules • Reports, • Forms, • Tables, and • Modules.

26. Page Breaks Leave at least two lines of a paragraph at the bottom or top of a page. Do not break a word over a page. Avoid separating notes, tips, important notes, cautions, and warnings from the material that they concern. Try to have at least five or six lines on the last page of a chapter. Commit Internal Training Session- Course code CMTED -003 26

27. Tables Place information that identifies the contents of a row in the leftmost column of the table. Make entries in a table parallel—for example, in a description column, be consistent in your use of beginning the entries with a verb or noun. Do not leave a blank column entry. That is, if the information doesn’t apply, use Not applicable or None. Avoid dividing a table between pages. Commit Internal Training Session- Course code CMTED -003 27

28. Notes and Tips Cautions A caution is a type of note that advises users that failure to take or avoid a specified action could result in loss of data. Important notes Positive information that emphasizes or supplements important points of the main text. Tips A tip is a type of note that helps users apply the techniques and procedures described in the text to their specific needs. Warnings A warning is a type of note that advises users that failure to take or avoid a specific action could result in physical harm to the user or the hardware. Commit Internal Training Session- Course code CMTED -003 28

29. Global Content Word Choice Foreign Words and Phrases Time and Place Fonts Commit Internal Training Session- Course code CMTED -003 29

31. Avoid surprising or humorous word choices, slang, and sarcasm.

32. Spell out geographical names, abbreviations are often ambiguous.

33. For example CST is always not ChhatrapatiShivaji Terminal

35. Foreign Words and Phrases Avoid non-English words and phrases, such as de facto or ad hoc, even if you think they are generally known and understood. They may not be, or the language may not be understood by a translator. Find a straightforward substitute in English instead. Commit Internal Training Session- Course code CMTED -003 32 Use these terms Instead of for example e.g. that is i.e. namely viz. therefore ergo

36. Time and Place To globalize time information, follow these guidelines: Avoid A.M. and P.M. notation. Use 24-hour time format Begin calendar weeks on Monday Spell out the names of months, use the format month dd, yyyy Do not use numbers to represent months, such as 7/05/2011 Avoid referring to seasons Commit Internal Training Session- Course code CMTED -003 33

37. Fonts Use fonts that are available in browsers and operating systems worldwide. Common fonts are Times New Roman Arial Courier New Verdana Commit Internal Training Session- Course code CMTED -003 34

38. Tone and Rhetoric Parallelism Anthropomorphism Humor Commit Internal Training Session- Course code CMTED -003 35

39. Parallelism Parallelism ensures that elements of sentences that are similar in purpose are also similar in structure. Use the Search command on the Start menu to locate the document and then open it. The Search command on the Start menu locates the document, and you can then open it. Double-clicking a document icon in My Computer opens a document. Double-click a document icon in My Computer Commit Internal Training Session- Course code CMTED -003 36

40. Anthropomorphism and Humor Anthropomorphism is attributing human characteristics or behaviour to things that are not human. In technical writing, there is an understandable temptation to anthropomorphize to make difficult material easier for the reader to relate to. Do not succumb to this temptation. Correct If you receive a confirmation message, the engine will store your data in the specified format. Incorrect If you receive a confirmation message, the engine will behave as you requested. Commit Internal Training Session- Course code CMTED -003 37

41. End of Session……. Commit Internal Training Session- Course code CMTED -003 38