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

2. Outline 1. Guidelines for Designing Reference Documentation 2. Decide what to include 3. Establish a pattern 4. Organize the reference section 5. Show how to use the reference information 2. Summary 2

3. Writing to Support - Reference Lecture: 12 3

4. Definitions of Terms (Glossary) Glossaries contain definitions of terms the user finds in the manual and need to understand in order to work the program There are two types of Glossary items: 1. Concepts that underlie the software: Examples include masks, shell, routers etc. Some may be defined in the related procedure but they all should be in Glossary section too 2. Terms relating to the subject matter of the software: For example, general ledger, grade point average etc. 4

5. What to Include in a Single Reference Entry Imagine you have a reference section in a manual containing commands of a program but still you need to answer what information to put in the description  Give a command and its brief descrption But you can have more than just that including the following elements;  Conceptual information  Structural information  How-to information  Technical information 5

6. What to Include in a Single Reference Entry (Continue…) Conceptual Information (Idea of the command)  Command itself  Definitions and descriptions of command and what it does  Explanation of how the commands affect the user’s work  Sample reports showing what the command produces Structure Information (Relationship of the command)  Access sequences to tell the user how to get to the prompt where commands works  Screens or menus showing where to find the command  Alternative commands such as keyboard  Cross references to tutorials, procedures and other entries 6

7. What to Include in a Single Reference Entry (Continue…) How-to Information (Use of the command)  Steps of executing the commands in tasks  Examples showing the commands in a syntax statements  Tips for when and how to use the commands efficiently  Error message when you use the command incorrectly Technical Information (Programming associated with the command)  File specifications for what files the command uses  Inputs i.e. what kind of data to use with the command  Warnings to prevent data loss when using commands  Syntax diagram telling how to use the statements 7

8. 3. Establish a Pattern Key to reference material lies in pattern The recognizable and flexible pattern of reference entries work well by selecting the following topics  Definitions (tell what the commands or function does)  Explanations (tell how to apply the commands or functions)  Examples/syntax (give the example of command or function in use)  Step-by-step (presents abbreviated steps for using the command or function)  Warning/cautions (let the user know what problem may arise) 8

9. 4. Organize the Reference Section There is no built-in sequential organization available to create reference You will have to decide what comes first and what comes next and so on. Two choices for organizing the reference documents  Alphabetical Does little support to the task orientation  Menu-by-menu Its enforces the task orientation to your work 9

10. 5. Show How to Use Reference Information Usually your reference section or document will require no instruction but with reference section containing multiple elements, you should tell the user what pattern you intend to follow The organization of the reference information is presented in introduction in form of some paragraph that should explain the following  Who should use the information  How you organized the information  Elements of each entry  Relation to the other section of the documentation 10

11. Understanding the Reference User Often the reference user know the software program well at-least better than the novice and casual users so the requirement of this user is quite different than others Observations about advance users  Do not like to waste time  Doesn’t like to leave screen to go looking for information 11

12. Understanding the Reference Entry The elements of your reference entry deserve special consideration and each element of the reference should try to answer the question an advance user may have in his mind about a command or function To understand the reference entry you have to look to the idea behind and what it contains 12

13. Understanding the Reference Entry (Continue…) Elements of a reference entry describes:  Access Information: what menu contains the function, the chain of commands user need to issue to access a function  Function Definition: What the function does  Associated Commands: What other keys or commands user needs to use to use the function efficiently  Qualifications/Special Cases: Field lengths, minimum or maximum allowable input, time limits etc.  Tips: How to use a function efficiently, shortcuts, commands, and potential problems 13

14. Understanding the Reference Entry (Continue…) Each of the entries answers a specification question  How do I get to the function?  What does the function do?  What other commands do I need to know about?  When can I use the function?  How do I use the function well? 14

15. Recap (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 15

16. 16 Summary Any Questions?