1 Technical & Business Writing (ENG-715) Muhammad Bilal Bashir UIIT, Rawalpindi

Outline 1. What is a Reference? 2. Guidelines for Designing Reference Documentation 1. Choose the right form of reference 2. Decide what to include 3. Summary 2

Writing to Support - Reference Lecture: 11 3

What is Reference? Reference documents also referred to as support documents includes all the look-up sections and elements of your manual and help The reference documents are associated with advance users: who know the software well, but need to look up specific elements that are too complicated to memorize and do not necessarily relate to step-by-step procedures 4

Guidelines for Designing Reference Documentation The guidelines include; 1. Choose the right form of references 2. Decide what to include 3. Establish a pattern 4. Organize the reference section 5. Show how to use the reference information 5

1. Choose the Right Form of Reference There are three forms of reference documents  Appendices  Update Information Sections/Readme Files  Job Aids With some programs you will design information in all three of the above forms whereas in others you may supply just ‘a quick reference” If the writer provides all three forms of reference documents, he can check the consistency among them 6

Appendices Contains some of the most valuable information relating to the use of the program This allows document writer to put all the highly detailed technical information that a highly technical person wants and use in the workplace The printed appendix contains information that are relevant and useful but not essential for all the users There are various kinds of information Appendices provided that has been explained ahead 7

Appendices (Continue…) Kinds of information appendices provide  Error message and explanations of how to recover from them  Filenames and extensions of files associated with the program  Troubleshooting tips  Matrices of compatibility with other programs  Charts showing program key combinations / shortcut keys  Printer driver charts showing capabilities with various printer brands  Frequently asked questions (FAQ) 8

Update Information Sections/Readme Files Consist of text files that accompany programs on the distribution disk or come when you download the software from an internet site Contains the following kind of information;  Installation details and Installation tips  Last minutes changes that are too late to be included in manual or online help  New features in recent release of a program  Revision histories  File descriptions  Contents of directories etc. 9

Job Aids Also called job performance aids are shorter forms of reference documentation It is repository of information, processes or perspective that is external to the individual and, that supports work and activity by directing, guiding and enlightening performance They exist in number of form  Keyboard templates  Cheat sheets  Laminated program overview cards  Quick reference cards 10

Innovative Forms: Flipcards Innovative forms makeup a special class of reference information It is very easy to put command information on foldouts, posters and back cover of the documents One such form is flipcard: a specially designed form that mounts a card on the monitor of the computer and contains brief overview of program information A flipcard is an interesting adaptation of job aid because it provides such useful highly focused reference information right at the user’s fingertips 11

Innovative Forms: Flipcards (Continue…) Features of flipcard includes;  Easy to read: You can easily flip to the kind of information you need  Contains a surprisingly large amount of information: A lot of information can be put together on it with small font size  Colored heading: The headings in red make the sections of information easy to find  Unique and interesting: The flipcard attach easily to the edge of the computer screen, thus delivering the information where user needs it  Afford easy access to information: You can easily get to information on cards simply by flipping from one to other 12

2. Decide What to Include First you identify the topic areas to cover as reference and then you will find overview of the kinds of information to include in a reference section There are three categorizes of information that can be included in a reference 1. Commands 2. Interface Elements 3. Definitions of Terms 13

Commands Commands refers to all the instructions the user employs to put the program to work Types of commands in references are:  Meaning of special function groups (e.g. Ctrl+C, Alt+Shift)  Explanations of set commands (e.g. set host, set path etc.)  Definition and use of format commands (e.g. )  Special procedure for using utilities (e.g. File transfer, Draw image etc.)  Explanations of toolbars  Definitions of Macros 14

Interface Elements Refers to the parts of the screen that the user sees and has to read and manipulate in order to put the program to work Information about interface elements would include following:  Explanation of menus  Definition of keys  Labels of screen regions  Explanation of rulers 15

16 Summary Any Questions?