What Is a Reference Entry?

A reference entry is a single source of information about a specific aspect of a larger topic.Typically, are useful in these instances:

• The subject has many topics, each with similar information
• Users have a little information and want more (in other words, for intermediate and advanced users rather than novices)
• Users need a communication product that lets them easily look up a one or more specific facts at a time

Typically, users are familiar with the subjects in references but have not memorized the information (and probably won't).

Common subjects of references include:

• Commands for programming languages and other types of software. Users usually seek information about a particular command; reference entries help readers easily find them.
• Definitions. Users usually seek a basic or expanded definition of an individual term. A reference with basic definitions is called a glossary or dictionary. References with expanded definitions are called encyclopedias.
• Corporate and government policies. Users usually seek information about a particular policy; they prefer not to read about all of them at one time. A reference of policies is usually called a policies and procedures manual.
• Style. Users need information about a particular rule of style, such as how to punctuate bibliographic entries. A reference on style is called a style guide.

Top

How to Write a Procedure

First, Some General Writing Suggestions:

• Acknowledge that the typical user is knowledgeable
• You can therefore unapologetically use terminology—but define key terms the first time they are used in each entry because users might not remember terms yet many will be embarrassed to admit it (also make sure you define terms in each entry, rather than entire reference, because you cannot assume that readers have seen other entries)
• Similarly, you may use acronyms but spell them out the first time you use them in an entry
• If users need prerequisite knowledge to understand the reference, indicate the skills they should master (such as name the 5 elements of work management) rather than books they should read. Only after listing the prerequisite skills users must master should you list the sources where they can find this information. Merely listing books or manuals doesn't tell users what they need to know, just where to find the information.

For example, write "you should be able to list the 5 elements of work management, as described in the Concepts Manual" rather than "You should read the Concepts Manual." In the later example, users have no idea why they are writing the procedure.

• Follow a clear, logical organization
• Users should immediately understand how entries are organized, with no or little additional explanation
• Use identical or nearly identical structures for each entry (varying only when absolutely necessary)
• Use parallel and identical headings to indicate similarities in structures and ideas

Using Templates to Ensure Consistency Among Entries One way to ensure consistency among reference entries is to develop a "template" on which to base each entry. The template contains each element of the entry that must be similar or identical to other entries, in the order they would be presented, such as headings and standardly used text. The template also contains any style guidelines that would ensure consistency. When writing a reference entry, then, a communicator would essentially fill in the form. An example of a template for descriptions of courses in a course catalog: Course Title About this Course A 50-word description, beginning with an action verb, such as Introduces or Explains. Do not use the words "This course presents.... or similar expressions. What You Should Learn List the objectives of the course, beginning each with an observable, measurable verb. Who Should Take this Course List job titles only, do not write a full sentence. Choose among these job titles: system administrators, system programmers, and end users. Another advantage of using templates is that they help promote consistency among different writers. If several communicators contributing entries to a single reference follow the same template, users are less likely to detect variations in the writing style. Variations cause confusion for users.

• Write consistently—maybe even identically—to reinforce similarities:
• Use identical words and phrases to explain identical concepts
• Similarly, when information in one entry is supposed to be identical to that in another, repeat the information verbatim
• Follow these additional writing suggestions:
• Note that users scan--rather than read--references.
• Whenever possible, present information in lists, charts, and diagrams so users can more easily find it.
• Write in short sentences and phrases. In many instances, you may use sentence fragments.
• Tell, don't teach. That is, leave out unnecessary explanations. Remember that readers don't really want to learn, they only want to "do."
• Be specific, not prolific

Second, Suggestions for Organizing Specific Types of Reference Entries:

You might have encountered some of these types of reference entries but these entries did not have all of the parts listed above. The parts of a reference entry that you actually include is based on the information that readers need.

Similarly, within reference entries, you should only include the information your users need. When you write these entries, however, make sure that each entry in a document has all the same parts. Users expect consistency among reference entries. For example, you might be writing a policies manual for employees who do not have the authority to administer the policies. You would omit the section on administration from each reference entry.

Finally, note that users should already be familiar with technical terms discussed in the reference entry. Provide a glossary of technical terms if you do not expect users to be familiar with terms.

Top

Examples

• Of a command description:

RUN Command RUN \directory\program-name Starts the program whose name is entered with the command. \directory\ names the directory in which the program is stored. If you do not enter a directory name, the system assumes the program is stored in the root directory. program-name is the name of the program to be run. You must enter a program name. Considerations None. Examples run \mydir\account Runs the program named account in the directory named mydir. run wordproc Runs the program named wordproc.

• Of a policy:

Educational Leave About the Policy: Allows employees to take up to 2 years off without pay to complete a degree program at an accredited university. Employees on educational leave are guaranteed a comparable job upon return if they receive passing grades in all of their courses. Administering the Policy: Eligibility: Employees who have a minimum 5 years' with the company, who have been accepted into a degree program at an accredited university, and who have satisfactory work performance. Benefits and Salary: Employees continue to receive health and dental benefits when on leave. They do not receive salary or other benefits. Part-Time Work: Employees on an educational leave may work up to 20 hours weekly. In this capacity, they will be considered supplemental employees. See "Supplemental Employees" for information about this program.

Top

models | processes | techniques | resources on i.d. business and management | home

(c) Copyright. 1999, 2000, 2001, 2002. Saul Carliner. All rights reserved.