Linked - Softouch Information Services
Contents
1. bin switch the bin cover must de closed for the switch to work Figure 6 Letraset Typeface Range Poster Letraset Corpora tion 1986 Open the bin cover place the paper in the tray and close the bin cover Press up on the bin switch to raise the din to its proper level Figure 5 3820 Page Printer Operator Summary IBM Corpo ration 1985 Posters not only make a product look good but make a product s function or list of attributes readily available to the user For example Letraset a manufacturer of rub on type publishes a font poster that illustrates all the compa ny s typefaces An example of each typeface along with the typeface name is illustrated for users in a 22 by 36 inch format Templates are often found on equipment with hardware Figure 7 WordPerfect Templates WordPerfect Corporation features that change in response to software function A 1387 good example is found on many modern telephones with i touchpads assigned meanings other than the alphanumeric keyboard template figure 7 This type of template can be name printed on the keys Using programmable tele placed on the keyboard for each different program being phones vou assign a key to dial any phone number and used The template identifies any unique key definitions the phone number that the key dials is listed to one side of that the program has For example with the Lotus tem the keypad on a changeable template plate the user of Fre2. page product man ual As a cook in a hurry or a desktop publisher with a deadline which would you choose As a manufacturer paying for all the printing costs which would you choose The answers should be obvious Consequently many procedures for today s products come as quick procedure guides Found on pay telephones bank teller machines and sophisticated office equipment these aids prompt us through life by using a mixture of text and graphics for their presentation 78 IEEE TRANSACTIONS ON PROFESSIONAL COMMUNICATION VOL 31 NO 2 JUNE 1988 Figure 4 FLEX 32 Computer Brochure Flexible Computer Corporation 1984 The example in figure 5 shows a procedural guide for placing paper in a large office printer A mixture of proce dural instructions and graphic illustrations guide a user through the task of adding paper to the input bin The rest of the small booklet details how to turn the machine on and off cancel a print job restart the printer and decipher any error messages encountered A survey of 20 users taken from people as they collected their output from the IBM 3820 printer revealed that 30 percent of the users had read the booklet no one had ever read anything else about the printer even though many other publications user and diagnostic manual paper ref erence manual etc for the printer were readily available Short task oriented procedures packaged in a quick refer ence save the user from
3. quick procedure guide does exactly that using die cut pages as a visual and physical indexing mechanism We should also note recent research in cognitive psychol ogy where Huckin 10 tells us to make the topic of each section visibly prominent by using headings and subhead ings and by placing topic sentences at the beginning of each paragraph Riley Schoeffler and Karhan 4 also suggest providing visually obvious cues that are redundant with the text for example colors pictograms and other symbols In the RolmPhone example the procedure again does exactly that highlighting the procedure with icons for each step of the individual procedure 82 IEEE TRANSACTIONS ON PROFESSIONAL COMMUNICATION VOL 3t NO 2 JUNE 1988 ROLMPHONE FEATURES ee ee Tene ee ee CONSULTATION CALL CONFERENCE CALL CALLBACK CAMP ON AUTOMATIC CAMP ON SYSTEM SPEED CALL STATION SPEED CALL AVE AND REPEAT CONNE TRANSFER HOLD HOLD allows you to temporarily hang up a line either to take a call on another line or to attend another matter without disconnect ing your caller To make a second call see CONSULTATION CALL HOLD PRESS HOLD HANG UP PRESS LINE BUTTON OF CALL BEING HELD PICK UP RECEIVER Figure 8 RolmPhone 120 240 400 Quick Reference Guide Roim Company 1985 Effective Headings Headings in quick reference should accommodate the read er s search for needed information 7 They can only do that if
4. quick reference documentation we can group quick reference documents into several different types and then examine each type for insights into their construction The following types of quick reference documentation are discussed Slide rules Syntax summaries Informational guides Posters and templates Slide Rules Reminiscent of the engineer s slide rule and perhaps a di rect descendent this type of quick reference is mechani cally operated and contains tabular data The tabular data are arranged in such a manner that cross table relationships can be recognized quickly For example in the table below there are two columns of numbers What is their relation ship to each other 0 18 10 23 20 29 30 34 40 40 50 46 The relationship only becomes obvious when overlaid with a template that provides the missing information The table is produced on a card that can slide through the template performing temperature conversions for the user figure 1 The user needs no mathematical concepts only the tool This type of documentation is interactive and helps the reader perform specific tasks This quick reference is not read from cover to cover but is looked at only when needed making it task oriented 0361 1434 88 0600 0075 01 00 1988 IEEE 76 IEEE TRANSACTIONS ON PROFESSIONAL COMMUNICATION VOL 31 NO 2 JUNE 1988 Figure 1 Stide Rule for Fahrenheit Cel
5. they Contain an action or agent State or answer a question In figure 9 there are four heading statements that answer the following questions for the user How do I start How do I save How do I clear the screen How do I exit Starting WordPerfect Two Disk Drives With DOS running and the WordPerfect diskette in drive A e Enter b to change the default drive e Enter a wp to start WordPerfect Hard Disk With DOS running e Enter cd personal directory name gt e Enter wp Saving Documents e Press the Save key e Enter a filename If the filename aiready exists on disk vou may either replace the old Tile with the document on your screen or you may enter another name Clearing the Screen e Press the Exit key e Enter a e Press the Enter key Exiting WordPerfect Press the Exit key e Enter n Enter y When you see the DOS prompt A gt B gt etc you may turn your machine off or load another program Always exit WordPerfect properly before turning off your machine Figure 9 WordPerfect 4 0 Quick Reference for the IBM PC XT AT and Compatibles SSI Software 1984 Robert I Williams a document designer interested in eval uating the effectiveness of technical documentation re minds us that headings have other objectives Titles have nuances 11 Williams suggests that we can use titles to emphasize subject matter and also bury material by giving it skimpy billing For example
6. Techni cal Communication 29 1 1982 10 Huckin T N A Cognitive Approach to Readability in New Essays in Technical and Scientific Communication 1983 p 91 11 Williams R I Playing with Format Style and Reader Assump tions Technical Communication 30 3 1983 p 11 When You re Editing Copy Don t guess look it up e Never be afraid to question a word or phrase that makes no sense to you Always ask whether something sounds dumb e Remember that just because something looks right doesn t mean it is e Keep in mind that an overlooked error is always easy to spot in the published copy Editors in the Training Branch U S Army Ordnance Missile and Munitions Center School Redstone Arsenal Huntsville AL
7. The trend is no different with high technology instructional ma terial As technical writers in the 1980s we are acutely aware of our readers demands for fewer pages and the echoing of that demand by our managers and our account ants While learning to do our job better we have become well drilled in the proverbial practice of cut cut cut Economy fashion and good writing are three forces working together bringing about the quick reference genre The popularity of this new packaging of information is growing and professionals in the field commenting on user documentation are saying things like the following 90 of the time 90 of the needs of 90 of the read ers can be covered in a simple summary card 1 e Quick references are a big time saver 2 User friendly means having a quick reference card 3 In support of the shrinking document research shows that Paul Reitman carned a B A in the writing program at the University of Colorado at Denver As an information developer at IBM he has been involved in the production of both traditional and online documentation for both hardware and sottware for both mainframes and PCs today s reader hardly reads any instructional material at all 4 and in response writers of instructional material have offered an alternative to the fat manual the quick refer ence What is a quick reference What does it look like and what does it do To better understand
8. a typical user s guide for a software program may be broken down and titled by func tion The raciest functions are often given larger head ings than those functions of the program that are not bug free at the time of the product s release For another example take the software product that converts data from i a competitor s product into a usable form If the competi tor is a close competitor the heading given the competi tor s product may be minuscule Williams concludes that every element of first impression counts every filling in or leaving out shapes the message REITMAN QUICK REFERENCES CONCLUSION With the economics of publishing joining forces with the fashionable demand for quick and clean documentation we can expect to see the quick reference message continue to be reshaped into even more compact forms As today s technical writers become more experienced with working clear writing techniques into quick reference documenta tion the shape of quick references will become even sharper better able to cut through the growing mire of in formation The shapes described in this paper the slide rule syntax summary informational guide quick procedures guide posters and templates will continue to change as this dec ade marches on Human factors testing on quick reference documentation is also evolving and will soon reveal the usability of the forms within this genre For now by prac
9. at Sometimes unique program information is included along with the syntax diagrams In figure 2 the command summary presents a listing of subroutine names and spe cific information about each subroutine One look at the subroutine JARSET shows that this sub routine is used to reset the primitive attributes to their default values and has no parameters indicated by Summaries of this type eliminate the need for a user to re fer to a more complete reference manual while operating the program A poll taken among 50 users of quick reference documen tation shows that most users look for syntax in a syntax JALOAD JASPEK Ali the DI 3000 subroutines are summarized in the foliowing alphabetical listing Each summary gives the parameters for that subroutine and a brief description of the subroutine s function Parameters are explained where necessary As in the A functional listing above subroutines marked E are part of DI 3000 EXTENDED those marked MJ are part of the Metafile System and those marked T are part of DI TEXTPRO DI 3000 EXTENDED the Metafile System and DI TEXTPRO are options to Di 3000 and may not be available at al installations An underlined parameter is returned from the subroutine indicates a range of values boid face indicates a system initialization defauit indicates no parameters JALOAD iARRAY Replace current primitive attributes with a previously saved array of att
10. eLance Plus presses Fl for HELP In contrast the WordPerfect template has the HELP key Another example of a common template is the computer identified as F3 Having templates for both the Lotus and 8O IEEE PRANSACTIONS ON PROFESSIONAL COMMUNICATION VOL 31 NO 2 JUNE 1988 WordPerfect programs helps a user keep track of key as signments between the two programs especially when the user must switch back and forth from one program to an other DESIGNING A QUICK REFERENCE Is quick reference documentation designed any differently than other documentation The answer is yes and no As you have seen from the previous classifications of quick reference documentation there are distinct design differ ences among slide rules syntax summaries informational guides and posters templates Size use placement in the work area and audience are all factors that appear to set quick reference documentation apart from its full blown predecessor the manual However quick reference docu mentation still fits well within the technical documentation family A writer experienced with traditional document design should feel equally comfortable designing quick reference documents Many design strategies that work well with large user manuals long reports and heavy catalogs also work well with the quick reference Creating Computer Software User Guides From Man uals to Menus a recently published book on user docu mentation by Doann Houg
11. hton Alico 5 contains the fol lowing design tips e Allow adequate white space e Print for legibility Group information logically e Include only relevant information Give readers easy access to information Design effective headings What do these proverbs mean in quick reference design White Space Houghton Alico calls on writers to allow adequate white space as do most researchers in this field What does this mean to someone working with small pages and miniature type sizes Does the guideline of 40 percent print and 60 percent space 1 apply here Or is the appli cation of white space more important than the ratio Brockmann 1 states that the emphasis should be placed on active white space space that separates units of infor mation and allows the reader to discriminate between sec tions rather than passive white space space that simply rings the perimeter on the page Active white space is also different from white space controlled by the selection of type style and type size When working with active white space in quick references writers need to take extra care to position the space effec tively regardless of traditional ratios Keep like informa tion together while separating groups of information with small carefully measured parcels of white space Use white space with type style and type size to create a visual hierarchy on the quick reference page Legibility Pocket Pa
12. l 6 reminds us that readability and legibility are not synonymous Readability is the ease of reading the printed page whereas legibility refers to the speed at which each letter or word can be recognized Our goal as writers of fast track information is to re move debris from the page and to use well oiled type Small typefaces often slow readers down but larger type faces take up more white space on an already reduced page size What should a designer of quick references do Avoid typefaces that have long ascenders and descend ers they require more leading e Print your quick reference on paper with a texture that does not interfere with a small typeface rougher tex tures often cause broken type Select a typeface that is legible at small point sizes Re member that the actual size x height of the letter is what counts and not the point size For example 9 point Century is more legible than 9 point Garamond 9 point Helvetica is in the middle of the legibility range Logical Organization Houghton Alico suggests that we organize our information logically We must then ask logical for whom Infor mation written for Captain Kirk probably needs to be structured differently than information written for Mr Spock In their exploratory research Flowers Hayes and Swarts 7 conclude that functional documents should be organized around actions rather than terms This immedi ately brings t
13. lass Schedule by contacting th IDE Administratar s Office 7 443 9940 BCRVM2 IVM244308 0 8 580 2 Reter to the Information Development Education IDE CLASS SCHEDULE or the 18 8 PG TECHNICAL EDUC TION GUIDE for additional information about courses The WIS amp PO Technical Education Guide describes a wide range of courses that you may need Figure 3 Information Development Education IBM Corpo ration 1986 Figure 3 illustrates a planning guide given to employees to aid them in planning their corporate education In this guide readers take a shortcut through a catalog of course descriptions class schedules and other information lead ing them down a quick career path Informational guides come in all shapes and sizes Take for example the Flexible Computer Corporation s infor mation guide see figure 4 This polygon shaped guide is made of flexible material that can be twisted and folded to reveal different panels of information Information is the only limitation in preparing a memorable guide Quick Procedure Guides With the arrival of sophisticated household and office equipment we have become increasingly dependent on manufacture supplied operating instructions From grinding with our Cuisinarts to desktop publishing with our laser printers we follow more and more procedures supplied by manufacturers The format for these procedures varies from instructions printed directly on the product to a 500
14. ng the quick reference our job is to cut and trim any excess information Test each sentence for relevance and importance The quick ref erence document should not be an all inclusive document Complicated or dangerous tasks might be better left in the manual allowing readers to absorb any background in formation they might need Don t be afraid to refer the user to the manual It is important that quick references offer a road map to another more complete source of in formation Information Accessibility The reader s ability to maneuver within the quick reference is so important that we either design maneuverability in or design usability out Take for example the 16 panel folding command summary for the AlphaBeta program 400 syntax diagrams all in an illegibly small typeface listed alphabetically on both sides of a folded strip of card stock that resembles an accordion Readers quickly retreat In a recent poll of 30 programmers who were given the choice of a short booklet style command summary or a long folded card stock format 80 percent voted in favor of the booklet style summary The physical format of the quick reference can make or break its popularity in reader opinion polls As a result of pay phone research Riley Schoeffler and Karhan 4 suggest dividing detailed information into re lated categories and using the category labels to construct an index The RolmPhone Quick Reference shown in figure 8 a
15. o mind one type of quick reference that defies such pioneering research In over 30 cases surveyed syntax summaries were found built around key terms commands subroutine names con trol words key words fields etc used within the soft ware program These key terms were listed in alphabetical or numeric order In figure 2 the program s key terms commands are listed alphabetically The writer organized the information without regard for any possible actions that the user operating the software might take Dr Spock a specialist from the advanced planet of Vulcan might un derstand this logical grouping the nonspecialist Captain Kirk will experience technical difficulties To make a syntax guide useful to both types of users the specialist and the nonspecialist the key words should be grouped together according to the user s actions and then listed alphabetically within each action group Flowers Hayes and Swarts also suggest that we organize information around the reader s questions and around the REITMAN QUICK REFERENCES user s actions Anticipate what the reader might ask first What is this all about To whom does it apply What do I have to do first For example consider figure 3 The question What do I do first is answered by using the document s structure the courses are listed in the order they must be taken The question Where do I get more information is an swe
16. oo ee Ty IEEE TRANSACTIONS ON PROFESSIONAL COMMUNICATION VOL 31 NO 2 JUNE 1988 a LA UA ELA re Co fic aa a Streamlining Your Documentation Using Quick References PAUL REITMAN Abstract You know one when you see one even though they come in all shapes and sizes The titles of these small hand held publications usually contain the word guide summary or reference Many of us in the documentation business have coined the terms job aid or quick reference to identify these small packages of information that readers can refer to at a moment s notice Quick references are small portable packages of information that can be seen in the pock ets of programmers high tech equipment operators and even shop pers at the grocery store But where did they come from What strange breed of documentation is this Is there rhyme or reason in the design of quick reference documentation This paper presents a description of various quick references and discusses their design WHAT ARE THEY AND WHERE DID THEY COME FROM During this 20th century age of miniaturization almost every household and office item has become smaller The spirit of human invention has been hard at work making everything in our lives more compact and easier to man age From automobiles to zero population growth we are becoming a society of smaller sizes Even those things that we read are becoming fewer in pages novelettes short stories picture magazines
17. pae REITMAN QUICK REFERENCES Writing and Editing 3891 ID Foundations Strategy mission and structure in IBM Pl 1 Defining User Tasks user s tasks and needs 3647 PM11 Controlling ID Projects Learn decision making techniques 2604 Writing Workshop 1 Writing Proce Improve your prewriting writing and 4643 Editing Skills Workshop Introduction to editing fundamentals 4 5649 Writing Workshop 2 Producing Qualit Learn to produce information that re understand and use 4 2605 Communicating with Graphics Sharpen your graphic communication skil 4 3897 Developing Transtatable Information Learn to produce information that can be ef 4 2025 Book Design for Non Designers 2607 Editing IBM Product Information 2608 Information Measurement and Testing 4 4768 Writing Workshop 3 The Writer s Voice For additional courses see reverse side Erene Here is a sample education plan for the writer or editor Did you recently join ID Learn about your profession its Learn to derive information requirements from a esi Learn the basics of book design and visual t Improve your technical editing skills mainly Learn to objectively assess information tor e Learn to control the personas in your writing 77 Communicating with Graphics Planning Designing a User Interface Managing Managers can a C
18. red up front right on the front panel Are these temporal orderings the only way to go Eliza beth Harris suggests not Harris 8 suggests that patterns derived from discourse semantics are also useful The use of spatialization by classification is one alternative accord ing to Harris This concept stems from the phenomenon that spatial relationships exist between some groups of in formation For example in a business letter the salutation comes before the closing remarks and in a manual the footnotes appear at the bottom of the page Put into practice spatialization by classification is exem plified by a font poster a poster pictorially listing all the fonts manufactured for a phototypesetter grouped by list ing all the fonts used for headings at the top of the poster all the fonts available for body text in the middle of the poster and all the fonts commonly used for footnotes at the bottom of the poster This spatialization helps organize the information for retrievability Another way to logically group information is to take a directional approach For example if describing the oper ation of a pasta machine use the pasta as a guide and de seribe each part of the machine beginning where the pasta enters the machine and closing with a description of where the noodles come out of the machine In support of the directional approach Britton 9 suggests we use a control statement that logically places the reader
19. ribute vatues JARC X0 YO Z0 RADIUS NSEG AO A1 Output an arc of a circle as a polyline picture element JARSET f Reset the primitive attributes to their default values JASAVE IARRAY Save the current primitive attributes in an application program array JASPEK DSPDEV RATIO Return the display surtace aspect ratio of a specific graphics dispiay device Figure 2 DI 3000 Quick Reference Guide Precision Visuals Incorporated 1985 summary first if available then turn to the user s manual In response writers should Group syntax logically Include only relevant information Allow easy access to syntax information by designing a quick reference or putting the information on line Informational Guides Informational guides have been around as long as the print ing process itself in the form of flyers and brochures Ad vertisers and politicians have used this form of communi cation for years and now technical communicators are jumping on the band wagon A technical information guide can outline a new product or announce a new service it is often used to shortcut the reader through miles of other less task oriented information This type of guide offers a fast path for a particular task by providing a quick summary of information much like the syntax summary described above Informational guides also serve as reminders and planning tools keeping the reader on track with just a glance
20. sius Conversion for the reader The guide eliminates the need for bulky look up tables Are there any drawbacks to this type of all in one tool This nonstandard design may be a problem for a physi cally impaired reader Some people turn pages without the full use of their hands and a mechanical design may not be usable Also the layout for a complex slide rule type guide is more complicated than that for a typed page The pasteup is tricky and printing costs rise as die cuts and assembly requirements are added Still a little effort from both the reader and the writer can overcome these problems Incidentally a poll conducted among a group of 50 computer users programmers and analysts revealed that only four percent of the population surveyed had ever used such a tool This relative obscurity can work in favor of a writer who has the desire to give readers something new renewed interest in a boring prod uct is always a feature that writers are encouraged to add Syntax Summaries Often included with today s software packages syntax summaries help the user work with the software The syn tax for the program is explained and the program s com mands that is subroutines control words key words field names are usually diagrammed allowing the reader to scan the command of all its possible parameters Typically the commands are arranged in alphabetical functional or numeric order and appear in a consistent for m
21. ticing Houghton Alico s proverbs Print for legibility Group information logically Include only relevant information Give readers easy access to information Design effective headings 83 we can build on what we know works while at the same time experimenting with different types of communication aids for our readers REFERENCES 1 Brockmann J R Writing Better Computer User Documenta tion New York John Wiley amp Sons 1986 2 McGehee B The Complete Guide To Writing Software User Manuals Cincinnati Writers Digest 1985 3 Bryant S F User Surly Software Computer Decisions 16 10 August 1984 p 114 4 Riley C J and Schoeffler C A Designing and Evaluating Standard Instructions for Public Telephones Bell System Techni cal Journal 62 6 Part 3 July August 1983 p 1827 5 Houghton Alico D Creating Computer Software User Guides From Manuals to Menus New York McGraw Hill 1986 6 Bruno M H ed Pocket Pal A Graphic Arts Production Handbook International Paper Company 1986 7 Flower L Hayes J R and Swarts H Revising Functional Documents The Scenario Principle in New Essays in Technical and Scientific Communication 1983 p 41 8 Harris E A Theoretical Perspective On How To Discourse in New Essays in Technical and Scientific Communication 1983 p 139 9 Britton W E Organizing the Technical Description
22. wading through hundreds of pages of product information and also give the impression that the product is easy to use Take for example instructions found inscribed on the face of a bank teller machine 1 Place your bank card in the slot below 2 Key in your password 3 Select a transaction from the menu This instruction set is short sweet and to the point Another attractive feature of a quick procedure guide is that it can be attached directly to the equipment in either label or booklet form Copier guides for instance are of ten built into the copiers themselves Posters and Templates Posters and templates replace taped notes stuck on com puter terminals and crumpled crib sheets tacked on walls Office graffiti of this nature is often vital information for the worker but usually an eyesore for the office manager and others as well Tastefully designed graffiti a poster or template quick reference can be both attractive and func tional In poster form the writing on the wall provides a lot of information in one quick look figure 6 REITMAN QUICK REFERENCES 79 Adding Paper to the Input Bin Open ihe bin cover The tray lowers automaticaily Fan the paper and place it in the tray Close the bin cover The tray rises automatically to the correct level To add paper to the bin al limes other than when ADD PAPER TO BIN 194000 is displayed tower the din manually by pressing down on the
23. within the material and then helps guide the reader through the remaining maze of information presented Brit ton contends that an unfamiliar object is less difficult to handle if a statement is made on the item s function thus telling us what it is For example an injection molding machine heats thermostatic granulate to a fluid state and forces the fluid into a mold under pressure The injection mold machine quick reference could then go on to describe the major parts of the machine by function heater injector granulate feeder The information is grouped logically within the document using the machine s functions as organizational headings Relevant Information Only With our quick reference information surrounded by white space typographically correct and presenting a logical grouping we can then concern ourselves with what is in cluded and what is left out Since we plan to put our quick reference information into a small apartment with one 81 small closet and no garage we must be very careful not to collect excess baggage As suggested by Britton 9 a con trol statement may function as a takeoff point what comes next needs to be scheduled and tested for its appropriate place in the material Britton concludes that technical information is often con fusingly conclusive much is clarified by omission Engi neers and scientists often want to tell everything there is to know and all at once While writi
Download Pdf Manuals
Related Search