Chapter Four _Reference

Writing to Support - Reference
Chapter Four
1 Fatima M.AbuHjeela
Writing to Support
 This is also referred to as Support Documentation, includes all
the look-up sections and elements of your manuals and help. It takes
forms like:
 Command descriptions
 Menu overviews
 Lists of definitions
 Function descriptions
 Examples
 Error messages
Writing to Support
 It associated with advanced users:
users who know the software well , but need to look up specific
elements of it that are too complicated to memorize .
 You should study ways to design reference information in task-

oriented way.
 Electronic and hypertext-based interfaces allow writers to design

online documents that use powerful and useful technology for
looking up information and relating it to workplace actions and
purpose.
Reference Guidelines
1- Choose the Right Form of Reference
 Reference user know the interface and usually come looking for a
specific piece of data to complete some task they themselves have
defined .
4
1- Appendices:
 It often contains some of the most valuable information relating to the use of the
program.
 It allow documenters to put all highly detailed, technical information that highly
detailed, technical persons would want and use in the workplace.
 Print appendix contains information that’s relevant and useful , but not essential
to all users.
 Appendix in software manual may contains:

- Error messages.
- Filenames and extensions.
- Troubleshooting tips.
- Matrixes of compatibility with other programs.
- ASCII charts showing word processor key-combination.
- Printer driver charts showing capabilities with various printer brands.
2- Readme Files:
 Text files that accompany programs on the distribution disk or come when
you download the software from an internet site.
 It contains the following kinds of information:

 Installation details.
 Last minute changes that are not included in a manual.
 New features in a recent release.
 File descriptions .
 Compatibility requirements with other programs.
 Etc.
3- Job Aids (Job Performance Aids) :
 These are shorter forms of reference documentation that includes

definitions, brief processes, command summaries etc.
 These are for people who already have basic training with the software.
 It is “ repository for information ,processes, or perspectives that is

external to the individual and that supports work and activity by
directing ,guiding performance.
4-Innovative Forms : Flipcards
 Type of documentation that are presented in special formats,

such as foldouts, posters, and flip-cards.
 The advantages of special formats like flip-cards are :

 Improve readability.
 Contain a lot of information.
 Make information more accessible.
 Use elements like color to help locate information
2- Decide What to Include
 You can include the following information in the reference section:
1- Commands :
 Refer to all the instructions used to work with a program.
 These include meanings of special function groups, explanations of set
commands, definitions of format commands, instructions for using
utilities, explanations of toolbars, and definitions of macros.
2- Interface Elements :
 It refers to the part of screen or command line of screen regions, and
explanations that the user sees and has to read and manipulate in order
to put the program to work.
 Information about interface elements would include the following:
explanations of menus, definitions of keys, labels of rulers.
10
Fatima M.AbuHjeela
3- Definition of Terms (Glossary):
 It contains definitions of terms that the user finds in the manual and needs to
understand in order to work the program.
 There are two kinds of glossary items:

 Concepts that underlie the software.
Examples: masks, shell, routers and so forth.
 Terms relating to the subject matter of the software.
Examples: general ledger,gutter…etc.
What to Include in a Single Reference Entry

 The following list of possible elements divided into grouping relating to the
kind of information each present to the user:
 Conceptual Information :
Emphasizing the idea of the commands and its function.
 Structural Information :
Emphasizing the relationship of the commands to other commands.
 Technical Information:
Emphasizing the software programming associated with the command.
3- Establish a Pattern
 The key to reference material lies in patterns, repeating the same
set of elements over and over again ,so the user become familiar
with reference .
 The following topics can be included in patterns:

1-Definition : Tell what the command or function does.
2- Explanation : Tell how to apply the command or function.
3- Example : Give an example of the command or function in use.
4- Step-by-step: present abbreviated steps for using the command or function.
5- Warning/cautions: let the user know what problems might a rise.
4- Organize the Reference Section
 You have two basic choices for organizing your reference section
1- Alphabetical Organization:
 Heap all the functions of the program together, regardless of the menu
structure, and go through them one at a time, starting with the a‘s.
 Drawback :
It does little to support the task -orientation of your manual.
4- Organize the Reference Section
 You have two basic choices for organizing your reference section :
2- Menu-by-Menu:
 You set up your reference section by menu, according to how the
user sees them in the program.
 You start with main menu then secondary menu, present each
menu, and then, in the subsequent pages, describe each of the
commands in the order they appear on the menu.
 The strong advantage of this is its reinforcement of the task
orientation of your work.
5- Show How to Use the Reference Information
 In many cases, your document required no instruction. Maps of menus or
summary of commands represent a self-explanatory reference page.
 You should tell the user - usually- in the introduction, the pattern you intend to
follow, so he or she establish it in his/her mind, set up the right expectation,
and it will serve as a reminder of how you organize each entry.
 Such an introduction should explain:

1- who should use the info, which type of users.
2- how you organize the info, alphabetical or menu bye menu.
3- element of each entry, list element of each entry.
4- relation to other section of the documentation, cross reference to other parts
of the document.
Practice and Problem Solving
 Write a tool bar Reference .
 Analyze Reference Formats.

Chapter Four _Reference

Uploaded by

Copyright:

Available Formats

Chapter Four _Reference

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Chapter Four _Reference

Uploaded by

Copyright:

Available Formats

Writing to Support - Reference

 You should study ways to design reference information in task-

 Electronic and hypertext-based interfaces allow writers to design

 Appendix in software manual may contains:

 It contains the following kinds of information:

 These are shorter forms of reference documentation that includes

 It is “ repository for information ,processes, or perspectives that is

 Type of documentation that are presented in special formats,

 The advantages of special formats like flip-cards are :

 There are two kinds of glossary items:

What to Include in a Single Reference Entry

 The following topics can be included in patterns:

 Such an introduction should explain:

You might also like