A Career in Technical Documentation
Contents
1. 56789 lt gt ABCDEF _Yabcdefghijklmnopgqrstuvwxyz 6 6789 lt gt ABCDEFG Yabcedefghijkilmnopgrstuvwxyz 6 789 lt gt ABCDEFGH abcdefghijklmnopqrstuvwxyz 6 89 lt gt ABCDEFGHI bcedefghijklmnopgqrstuvwxyz ra 9 lt gt ABCDEFGHIT gt a oN iehi jetmnopar selv uv xyz r Y EF p e E i lt gt ABCDEFGHIJK ierni jeinnopar selv vweyz S or 56789 GABCDEFGHIJKL efghijklmnopqrstu me jia raagr 93 ree ABCDEFGHIJKLM fghijklmnopqrstuvwxyz a ee eo 89 lt S ABCDEFGHIJKLMN ghijklmnopgqrstuvwxyz 8 Et ey 23456789 lt gt ABCDEF GHIJKLMNO hijkimnopaqrst a aia sa y 0 3456789 lt gt ARCDEFGHIJKLMNOP ijklmnopqrstuvwxyz amp 01234567 9 lt DEF JKLMNOPQ siimnopgrstuvwaye Insta 44 012245678 gt Ab cDEFGHIJKLMNOPQR klmnopgrstuvwxyz 6 ee 013 Le CDEFGHIJKLMNOPQRS lmnopqrstuvwxyz amp 0123 154 gt MBCDEFGH JKLMNOPORST mnopgqrstuvwxyz S amp e 01234 v4 2 ABCD TKENNOPQRSTD nopqrstuvwxyz ie 0123456789 lt ABCDEF 2 MNOPORSTUV opqrstuvwxyz INESSE 0323456789 gt lt gt AB IJKLMNOPQRSTUVW parstuvwxyz eye TEO i Z gt 2gRBCD FGHIJKLMN AE a qrstuvwxyz 5 6 ma gt GHI 9 STUVWXY rstuvwxyz S oh 01234567891 lt gt 2 F OPQRSTUVWXYZ stuvwxyz S5 6 x 56789 lt gt 27 AB D a tuvwxyz2. 6789 ays gt QABCDEFG KLMNOPORSTUVWXYZ Uvwxyz 3 amp Fes gt ABCDEFGHIJKLMNOPQRS TUVWXYZ vwxyz amp eo QABCDEFGHIJKLMNOPORSTUVWXYZ wxyz amp 0123456789 lt gt ABCDEFGHIJKLMNOPORSTUVWXYZ _ xyz amp 0123456789 lt gt ABCDEFGHIJKLMNOPORSTUVWXYZ _ Yz amp 0123456789 lt gt ABCDEFGHIJKLMNOPQRSTUVWXYZ a Z SSE 0123456789 lt gt ABCDEFGHIJKLMNOPORSTUVWXYZ _ ab S E 0123456789 lt gt ABCDEFGHIJKLMNOPORSTUVWXYZ abc SS amp 0123456789 lt gt ABCDEFGHIJKLMNOPORSTUVWXYZ _ abcd SSE amp 0123456789 lt gt GABCDEFGHIJKLMNOPQRSTUVWXYZ _ abcde wINESS Er x4 10123456789 lt gt ABCDEFGHIIKLMNOPORSTUVWXYZI 1 Yabcdef This page intentionally left blank This page intentionally left blank The Art of Technical Documentation Katherine Haramundanis dli loli ltali Digital Press Copyright 1992 by Digital Equipment Corporation All rights reserved No part of this publication may be reproduced stored in a retrieval system or transmitted in any form or by any means electronic mechanical photocopying recording or otherwise without prior written permission of the publisher Printed in the United States of America 987654321 Order number EY H892E DP Text and cover
3. Annie agrees to maintain the programmer s manual and to create a new reference card The other writers agree to their assignments of administrator s manual user s manual help text and troubleshooting manual Larry assigns the installation guide to himself in addition to a second book the error message manual Larry concludes his meeting and returns to his office where he makes his final edits to the documentation strategy and copies the completed file to the public area on the large computer system The public area contains files that others in the company can copy and print at their local sites by accessing the files over a network Use common directories and electronic mail He then sends electronic mail to the writers the development team the prod uct manager the customer services people and those who have expressed an interest in seeing the documentation strategy informing them that the strat egy is available he asks them to return comments within two weeks After lunch Larry attends a development meeting The room is already nearly full with developers qualification engineers testing people and writ ers Desultory discussions about equipment issues cease when the develop ment project leader arrives carrying two small computer tapes He holds one of them up and asks I have this morning s software version here on this tape is there any reason I should not send it to our field test sites This question prom
4. Quality in Technical Documentation 2 Accuracy 3 Completeness 4 Usability 4 Clarity 5 Readability 5 Logical Progression 6 Conciseness 6 Appropriateness of Language 6 Grammaticality 7 Appropriateness of Content and Scope 7 Appeal of Package 7 Further Reading 8 2 A Career in Technical Documentation Example of a Project Team 12 Writing Tasks 14 Career Growth in Technical Documentation Documentation Management 16 The Singleton Operation 16 The Separate Writing Group 16 Part of Engineering 17 The Outside Documentation Consultant 17 Further Reading 18 xiii 15 3 Precepts of Technical Documentation 19 Work Methodology 20 Know Your Subject 21 Technical Concepts 21 Use of Technical Experts 21 Know Your Reader 22 Writing for the Novice 24 Writing for the Experienced User 25 Writing for the Computer Operator 26 Writing for the System Manager Administrator 26 Writing for the Information Systems Manager 26 Writing for the Programmer 27 Writing for Other Industries 28 Writing Technical Reports and Marketing Literature 29 Your Technical Training 29 Know the Rules 30 Organization of Material 31 Format Considerations 32 Categories of Technical Documents 34 Organizational Elements of Technical Documents 42 Terminology 48 Style 50 Know Your Tools 67 Further Reading 68 4 Development Techniques 70 A Typical Writer s Workplan 71 Sample Writer s Workplan 72 The Quality Documenta
5. design Sandra Calef Production Editorial Inc Kathryn S Daniel Production Manager Composition Paul C Anagnostopoulos and M Dean Hendrick using ZzTEX Copyediting Dianne Wood Index Lois Oster Quotations from the following works appear as epigraphs in this book Blaise Pascal Pascal The Provincial Letters translated by A J Krailsheimer Penguin Classics 1967 copyright A J Krailsheimer 1967 reprinted by permission W K Heisenberg Physics and Philosophy The Revolution in Modern Science copyright 1958 HarperCollins Publishers reprinted by permission S N Kramer The Sumerians copyright 1960 The University of Chicago Press reprinted by permission quotation on page 143 from Donald Knuth TgX and Metafont reprinted courtesy of the American Mathematical Society Trademarked products mentioned in this book are listed on page 267 Views expressed in this book are those of the author not of the publisher Digital Equipment Corporation is not responsible for any errors that may appear in this book Library of Congress Cataloging in Publication Data Haramundanis Katherine 1937 The art of technical documentation Katherine Haramundanis p cm Includes bibliographical references p 235 and index ISBN 1 55558 080 7 paper 1 Technical writing Title T11 H28 1992 91 34993 808 0666 dc20 CIP Contents About This Book 1 Technical Documentation Defined Types of Technical Documents 2
6. of Electronic Text Editors 168 xii Features of Graphics Editors 171 Information Structure Support 172 Features of Text Formatters 177 Features of Text Formatters 178 Features of Page Layout Software 182 Computer Components 196 Computer Components 197 U S Book Paper Standards 212 U S Bond Paper Standard 212 A Series European Paper Sizes 213 Tables About This Book Who Is the Audience of this Book If you are a novice technical writer who works in the computer industry or are considering such a position this book is for you Read this book from start to finish don t skip around This book will help you become a better writer and you ll find references and suggestions for further reading when you want to extend your knowledge To get the most from this book you should have the following skills and experience be well trained in writing English have had exposure to computer systems have taken at least one course or had experience in expository writing such as doing investigative reporting or writing material based on fact have taken introductory courses in computer science and a science such as geology biology physics or astronomy understand the logical flow of ideas What Is the Thesis of this Book The thesis of this book is that the practice of technical writing is not the same as that of scientific writing that it is closer to investigative reporting When you create technical documentation you need to gat
7. plans for Version 1 1 documentation strategy for Version 1 1 and TIP 10 assignments He ends his list with other to encourage discussion of topics not covered previously By 10 05 he starts his meeting Jamie Junior a novice writer who has been on the project for about eight months and who is new to X asks when she needs to give her last book the in staller s guide to production the group that will prepare camera ready copy Because the software was not done when expected the final software date has been delayed by two weeks Jamie asks if she should keep her book open for the two week period After some discussion and after hearing from several other writers on the project Larry advises her to complete her document as planned but to check with him when she plans to hand her files to production Annie Able writer of the programmer s reference manual also asks about the changed date Will it affect her book After more discussion Annie agrees to complete her book on the date planned Larry passes out the new version of the documentation strategy points out the changes he has made and suggests tentative writing assignments Jamie will update three small documents for the next version and agrees to write the Release Notes This is a specially challenging assignment because she must work very closely with development during the last few weeks of the project and keep up with a steady stream of changes during field test
8. when you are writing technical documentation be aware of the ambigu ity of what you write and examine your work to eliminate ambiguity wherever possible Readability Your text and document must be readable What does this mean If your document is readable your reader will understand it For example if you are writing for experienced programmers you can expect they will be familiar with the technical terms of the trade But if you are writing for novices you need to explain all your terms and be particularly careful in consistent use of those terms Otherwise you will confuse your readers Readers don t expect synonyms in technical documentation in fact they will be confused by an alternative word and may wonder if you are introducing a new concept If you like you can use a readability test software program to help you determine if your prose is written at the level of education expected of your reader You ll find more about readability in Chapters 6 and 7 Quality in Technical Documentation 5 Logical Progression Your text must flow in a logical progression from simple to more complex or from start to finish of a procedure To some extent writing logically is part of writing clearly but logical progression should be evident in your organization of information and in how you approach your subject Conciseness Avoid verbiage and keep your sentences and words as short as possible Learn to discard ruthlessly words that add
9. High quality technical documentation is Accurate Complete Usable Clearly written Readable Logically presented 2 Technical Documentation Defined Table 1 1 Technical Documentation Types Marketing brochure case study sales pamphlet press release product handbook product catalog marketing script marketing talk sales presentation technical summary advertising copy white paper mock paper testimonial data sheet product brief application guide Concise Reporting magazine article newspaper article journal article internal publication technical paper progress report internal report annual report blueprint Written with appropriate language Grammatical Appropriate in content and scope Presented in an appealing package Accuracy Instructing customer manual user manual instruction manual site preparation manual installation manual owner s manual reference manual maintenance manual system manager s manual operator s manual technical description functional specification user interface specification glossary training manual quick start guide presentations course materials An accurate document contains neither errors of fact nor misstatements that will confuse the reader For example when you write that to perform a task the user should press the key and the user really needs to press the CONTROL and keys simultaneously you make an error Or you m
10. So Baie be ge E Kedah GHALIUALMNOPORSLIUVWAYLS HLUKLMNU I JKLMNOP Ly fea 70 JKLMNOPQRSTUVWXYZ _ VYabcedefghijklmnopaqrstuvwxyz I S 6 e 012 K LMNOPORSTUVWXYZ _ Vabedefghijklmnopgqrstuvwxyz 6 70123 Coo A Yabcdefghijkilmnopqrstuvwxyz amp 01234 MNOPQRS jklmnopqrstuvwxyz amp 012345 NOPORST klmnopaqrstuvwxyz amp 0123456 OPORSTUVW d lmnopqrstuvwxyz amp 01234567 PORSTUVW DEA E eee edness ORSTUVWXY BERRE al Do 0123456789 RSTUVWXYZ x a8 0123456789 STUVWXYZ _ sab tei jimo a JE in 0123456789 3 TUVWXYZ _ Vabedefghijklmnopaqrstuvwxyz amp 0123456789 UVWXYZ abcdefghijklmnopqrst he Ani mund 3456789 Sa VWXYZ _ Tao eee rine Hara anis j lt gt WXYZ _ Yabedefghijklmnopqrstuvwxyz amp 0123456789 lt gt XYZ EA Yabcdefghijklmnopgrstuvwxyz amp 0123456789 lt gt 2 Y Z _ abcdefghijklmnopqrstuvwxyz amp e 0123456789 lt gt A i tee Yabcdefghijklmnopqrstuvwxyz 123456789 lt gt 7QAB NT SE Fas a aara heda edadea a Wont alo ON BA AA fa me DA eras LY 8 is Yabcdefghijklmnopgrstuvwxyz 23456789 lt gt ABC Yabcedefghijklmnopqrstuvwxyz 3456789 lt gt ABCD _Yabcdefghijkimnopqrstuvwxyz 456789 lt gt ABCDE _ abcdefghijkimnopqrstuvwxyz
11. at your documents and information packages become more effective You can conduct your own usability tests you don t need an elaborate laboratory setup to do this testing more on this in Chapter 4 Clarity Write the text in your document clearly Follow the rules of good writing and trust your reviewers to help you find those muddy passages or that flawed logic Even a reviewer who just puts a question mark in the margin of your draft helps you improve the clarity of your document If that reviewer doesn t understand what you wrote others won t either Take the opportunity to dis cuss the information in the confusing paragraph or sentence with your re viewer You will very likely find there is another way to present the information that is more clear The prize for ambiguity in writing belongs to the order issued by British headquarters at the battle of Balaclava 1854 to advance rapidly to the front and try to prevent the enemy carrying away the guns The intent of the order was for the Light Brigade cavalry unit to retake guns that had just been captured by the enemy the result was that the Light Brigade charged an entrenched enemy position in the opposite direction and was slaughtered Most of what you write won t have such dire consequences but if for ex ample you are describing a software application that controls a nuclear power station you might find that what you write is a critical piece of documentation So
12. ation for more on the Great Attractors see Chapter 6 Most technical documentation is written in a rather formal style For exam ple when you write a computer manual you will avoid slang and contractions This book although about technical documentation is less formal than much technical documentation it is not a computer manual so I take some liber ties with my writing style A good way to find out what language style is best for a specific piece is to read other pieces written for the same reader That helps make you familiar with the terminology and phraseology of the subject about which you will Technical Documentation Defined write Of course if you are developing a piece for a wholly new readership you have to rely on yourself and your reviewers to ensure that you use the right mix of words tone and phrases You may be able to examine competitive literature for ideas about appropriate writing style You will find examples of several writing styles in this book Grammaticality Be sure all your sentences and phrases are grammatical Readers will give up if you make too many grammatical errors These errors include errors in spelling and punctuation as well as errors in grammatical form For example the sentence The motor shut down when you press the disable key is ungrammatical because the subject motor and the verb shut are not in agreement The verb should be shuts Ask a copy editor or
13. heckers 184 Translation Aids 185 Language Analysis Tools 185 Software System Tools 186 System Features 186 Code Management Systems 187 Specialized Authoring Tools 188 Further Reading 189 Computer Hardware System Hardware 193 Personal Computers 193 Workstation Systems 194 Minicomputers 195 Mainframe Computers 195 Feature Comparison of System Hardware Input Devices 197 Keyboards and Mice 197 Imaging Systems 198 Scanning Devices 198 Output Devices 198 Printers 198 Video Screens 201 Hardware Used to Create Your Book 202 Further Reading 203 Contents 191 195 9 Conclusion 204 A Societies Conferences and Journals 205 Societies 205 Conferences 207 Journals and Magazines 208 B Standards 211 Cc Timeline of the Development of Writing 214 Glossary 217 Select Bibliography 235 Index 255 Contents Figures 4 1 The Writing Process 71 4 2 Documentation Workplan and Process 74 4 3 Schedule Graph 86 4 4 Map Before Usability Testing 96 4 5 Map After Usability Testing and Modifications 97 4 6 Flow Chart of Starting YourCar 98 4 7 Nassi Shneiderman Diagram of Starting Your Car 5 1 Sample Bar Chart 114 5 2 Sample Chart with X and Y Axes 115 5 3 True and Optical Centers 116 5 4 Placement of Two Graphics on a Page 117 5 5 Placement of Graphics in T Shape 117 5 6 Stack 118 5 7 Linked List 118 5 8 Hypertext System 118 6 1 Image Area Gutter Margin 123 6 2 Por
14. her information rapidly and identify audience these are tasks the scientist need not perform Scientists are thoroughly trained in their respective fields and know their audience well their readership is primarily their colleagues people trained in their field Further technical documentation is as much an art as a science Its prac tices can border on the intuitive and require creative thought on your part The work you do requires creativity and problem solving skills and you must use your imagination to write technical documentation though what you write won t be fanciful it s based on fact You apply analytical thought to dis sect and understand the information you gather but there are few rules on xiii xiu how to gather information or how to put that information together in a way that your reader will understand most readily When you gather information you learn to work with your technical re sources and you learn from your reviewers When you prepare your docu ments your appreciation of your readers what they know and their reasons for using the documentation come into play This is where new techniques are still being developed for the technical documentor Your art consists of the techniques you master to gather understand and distill your technical information you show your craft in the effectiveness of your documentation and in your proficiency with your language and your tools The field of technical doc
15. ight omit a step in a procedure or add an extra space in a command line You can commit these errors if you write your document hurriedly or don t become familiar with your product You should also verify or have someone else verify any procedures you write Quality in Technical Documentation TIP Take the time to verify your facts A good way to verify a procedure is to draw a flowchart or a Nassi Shneider man diagram see Chapter 4 of the procedure This can often show missing steps or steps that lead nowhere Another effective way to verify a procedure is to have someone who does not know the procedure follow your written text and perform the procedure The tester can mark up your written text or you can watch the tester follow the procedure and note any difficulties the tester has For more on these techniques see Chapter 4 Completeness A complete document does not leave out something that is important to the reader For example if you write a reference manual be sure that it contains all the commands or statements of the product If you write a procedure be sure there are no missing steps Or if you write a manual to describe the error messages the user can see on a system make sure it contains all the error messages If you leave even one out and the user sees that one on the system confidence in the completeness and accuracy of your documentation will be eroded So check your document carefully to be sure you ha
16. literary editor or perhaps a writing peer to review your work Their con structive criticism can be invaluable in helping you find and correct such er rors Spell checking software can find some spelling errors but it won t warn you about grammatical errors If you are not sure about your grammar enlist the aid of another writer or an editor or consult a grammar book You will find the names of some good grammar books at the end of Chapter 3 Appropriateness of Content and Scope Your piece must have appropriate content and scope For example there is no point writing a piece for the novice that contains all the details only an expert could want to know and there is no point writing a step by step user manual for an expert who will find the progression of thought and exposition much too slow You can verify your content and scope by checking your table of contents against the norms for your readers by contact with your readers or potential readers and from your technical resources Appeal of Package The excellent book you have written won t be read if the packaging that presents it to the reader is awkward messy or hard to use If possible work with those who guide the printing process to ensure that your document resides in an attractive package when it reaches your customer Part of packaging is binding which is discussed in Chapter 6 Consider the convenience of your reader the lifetime of your book and how frequently
17. no information to your text For example avoid phrases such as in order to to does the job You can find these extraneous words by actively reading what you have written Also read what you have written after an interval some read their words aloud Always use a short word rather than a long one if the two words have the same meaning For example don t use utilize when use will do Many style books contain lists of such short substitutes for long and pompous words and phrases When you must get information across instantly use the one page display distill critical information to a single page You will need to put a lot of thought into a one page summary of anything complex but such a piece can be extremely effective You will often need to use a diagram or a table to compress information onto a single page Command lists balance sheets and reading paths are examples of one page representations of critical informa tion For an example of a one page8 display see Figure 4 5 Appropriateness of Language Establish the language that is appropriate for your intended reader When you write a sales brochure for example you have perhaps twenty seconds to catch the reader s interest your text must be brief So using the right words and the ideal turn of phrase is critical The shorter your piece the more important each word it contains A sales piece will use at least one of the Great Attractors of technical document
18. ntation if the article de scribes a technical subject related to computers and if the writer handles the subject without exaggeration or gross inaccuracy In some engineering organizations documentation includes the parts lists for a product or the engineering drawings or specifications prepared by engineers but you won t usually work on this type of document except per haps as a technical editor This book primarily addresses the writer creating original technical documents rather than the editor of documents written by someone else Types of Technical Documents There are three types of technical documentation marketing materials mate rials that report and instructional materials Marketing or sales pieces are intended to convince or persuade pieces that report state the facts without a persuasive or instructional slant and in structional pieces can both instruct and train Pieces that instruct include tra ditional documents that describe a product for the user Sometimes you may have opportunities to provide materials for use in presentations Table 1 1 shows the documents you may write in these three categories This book primarily addresses writing instructional materials in the computer industry Now that you have a view of what technical documentation is you need a perspective of what makes high quality in technical documentation This is the subject of the next section Quality in Technical Documentation
19. ods for testing documentation Chapter 5 describes the use and preparation of graphics important components of most technical documentation Chapter 6 describes considerations of information representation to provide insights on how different representations affect reader perception of your documents Chapter 7 describes some currently available tools and compares popular documentation tool methodologies These tools exemplify current tools new tools will evolve from them About This Book Chapter 8 describes representative hardware systems used in preparing technical documentation New hardware for documentation also evolves and this chapter provides only a snapshot of some current systems Chapter 9 presents a brief conclusion Appendix A lists and briefly describes professional societies conferences and journals relevant to the work you do Appendix B contains lists and tables of relevant standards Appendix C shows a timeline of milestones in the development of writing and writing tools The book ends with a glossary of terms an annotated bibliography of books and papers and an index A Word about Style and Conventions The writing style of this book is deliberately gender neutral The style favors non gender specific words such as author writer engineer programmer or developer and avoids words like he or she You will also find a few professional tips indicated by the word TIP and an arrow off
20. pts a lively discussion with comments questions and A Career in Technical Documentation
21. r at X Corporation for eight years In that time he has worked on four different software products and is now documentation project leader for the Xproduct a software system that runs with the ABC operating system Larry s job as project leader is to coordinate the work of the other writers ensure that they keep up with software changes and be a resource to them Larry starts his day at 8 05 a m when he drives into the large X facility along Route 495 in Marlboro Massachusetts His well lit office on the third floor contains color coordinated office furniture a terminal and a work station system His neighbors include developers working on the Xproduct software as well as other writers working on the project Larry sits down and taps the Return key on his work station the screen comes to life displaying a password window After entering his password he opens a window to read his mail and then opens another to make changes edits to a document he needs for the writing team meeting he will run scheduled for ten o clock By 9 55 Larry has completed his strategy document and run off ten copies for his meeting He picks up his project notebook and walks down the aisle to the conference room he has reserved A writer is there already and they chat amiably as the other writers enter the room in twos and threes Write out your agenda for all to see Larry writes his agenda for the meeting on the whiteboard current status of Version 1 0
22. set at the side of the page Acknowledgments People and libraries have been essential to the success of this document Those who have helped with technical information include Doug Borsum Dave Eklund Jim Flemming John Francini Marty Friedman Richard Han sen William A Hunzeker Susan Hunziker Dick Howard John Hughes Scott Jeffery Steve Jensen Rob Limbert Sarah Masella Dan Murphy Chuck Mur ray Robert Pariseau Carol Perlman Ton Holly Platnick Andy Puchrik Dick Rubinstein Tara Scanlon Ben Shneiderman of the University of Maryland Nicole Yankelovich of Brown University and Jan Walker of Digital s Cam bridge Research Laboratory Reviewers who have spent long hours commenting on drafts of this book include John Herrmann Dick Howard Tara Scanlon Dr Peter Jordan of Ten nessee State University Dr Robert Krull of Rensselaer Polytechnic Institute Molly Miller of Ascend Communications Inc Linda Pesante of Carnegie Mel lon University Carole Yee of New Mexico Tech and several anonymous re viewers you know who you are To these dedicated professionals I owe my sincerest thanks I am also grateful to my management Susan Porada Kathy Richer Susan Gault and William Keating for their support in this project allowing me to use Digital Equipment Corporation computer facilities to create my drafts and graphics The libraries of Digital Equipment Corporation Northeastern University J V Fletcher Library Westford Ma
23. ss Chelmsford Public Library the Stevens About This Book xu Memorial Library North Andover Mass and Boston College have been most generous in lending books I also acknowledge with sincere thanks the support and wise counsel of my editor George Horesta The opinions expressed in this book are mine and do not necessarily reflect the views of Digital Equipment Corporation I have benefited from the advice and comments of my technical resources but any errors remaining in this book are of course mine About This Book The Art of Technical Documentation This page intentionally left blank Technical Documentation Defined 1 Things are always at their best in their beginning Blaise Pascal Pascal The Provincial Letters No 4 1656 7 When you write technical documentation you follow a discipline and create specialized types of material The techniques you learn to use are generic you will find that you can use these techniques whether you are developing documentation for computer hardware or computer software You can also use these same techniques when you create technical documentation in other industries and for other business environments This chapter describes what technical documentation is and what consti tutes technical documentation Technical documentation is both the work you do when you prepare technical documents and the result of your work This double meaning for the phrase is like the double meaning of the
24. tion Process 75 Research 75 Understanding 76 Planning 81 Writing Your Documentation 87 Reworking Your Documentation 89 Receiving the Results 106 Further Reading 106 vi Contents 5 6 7 Graphics in Technical Documentation How to Prepare Graphics 111 How to Use Graphics 113 How Not to Use Graphics 115 How to Place Graphics on Your Page 116 Visualization 117 Further Reading 119 Information Presentation Tools The Great Attractors of Technical Documentation Page Layout 122 Page Details 124 Reader Level Formats 126 Readability 127 Punctuation in Technical Documentation 131 Special Notation 138 Tables 140 Book Design 140 Typography 142 Printing 144 Types of Paper 145 Bindings 146 Screen Layout 146 Combined Media 147 Information Retrieval 149 Hypertext Systems 150 Human Computer Interfaces 154 Alternative Media 157 Further Reading 159 Text Editors 164 EDT 165 EMACS 165 TeachText 166 LSE TPU 166 vi 166 Contents 122 110 121 161 vii 8 viii Graphics Editors 169 DECwrite 169 Adobe lllustrator 170 Micrografx Designer 170 Support for Information Structures 170 Text Formatting Software 171 DSRitroft dtroffInroff RUNOFF 173 Scribe 175 TEX 176 Page Layout Systems 177 VAX DOCUMENT 179 Interactive Page Layout Systems 180 Interleaf 181 PageMaker 181 Language Tools 183 Electronic Dictionaries 183 Spelling Checkers 183 Grammar C
25. trait and Landscape Orientations 124 6 3 Bleed Tab 124 6 4 Railroad Diagram 139 6 5 Odd Sample Head 142 6 6 Character Cell Terminal Interface 147 6 7 Overlapping Window System 148 6 8 Intermedia Electronic Editor Screen 151 6 9 Intermedia Web Screen 152 6 10 Intermedia Overlapping Text and Graphics Screens 6 11 Concordia Link Screen 154 6 12 Concordia Text Input Screen 155 7 1 System Types for Use in Technical Documentation 8 1 Processing and Printinga Document 202 99 153 163 Tables Technical Documentation Types 3 Readers from Two Industries 29 Sample Primer Outline 35 Sample User Manual Outline 35 Sample Application Guide Outline 36 Sample Hardware User Guide Outline 37 Sample Utility Manual Outline 37 Sample Database User Guide Outline 38 Sample Concept Document Outline 40 Sample Introductory Language Manual Outline 40 Sample Quick Start Guide Outline 41 Basic Procedure Table 47 IF THEN Procedure Table 48 Short Words 53 Extraneous Expressions 56 Words That Are Often Misused 57 Foreign Terms 58 Misspelled Words 62 Troublesome Plurals 62 Plurals of Compound Nouns 63 Plurals with Compound Adjectives 64 Latin and Anglicized Plurals 64 Doubling a Final Consonant 65 Words that End with a Double Consonant 65 Adding ly 66 Adding ness 66 Adding a Prefix 66 Words that End with Silent e 67 Sample Documentation Schedule 85 Readability Tests 129 Features of Electronic Text Editors 167 Features
26. umentation is more than just its day to day practice Its industrial practitioners are paralleled by a body of scholars in academia who help to explain and enhance professional practice I cite aca demic references in text at the end of each chapter and in the Select Bibli ography You ll find short titles and author date in the references in text or at the end of each chapter the bibliography is alphabetical by author What Is the Structure of this Book This book is my view of what it takes to produce effective technical documen tation This is not a style guide that deals with all aspects of typography and copyediting but presents for your use the distilled knowledge of my experi ence After preliminaries you ll find general precepts then three chapters that address practice and techniques The last major chapters summarize and compare software and hardware tools you are likely to encounter Appendices gather reference material In more detail Chapter 1 defines technical documentation and describes quality in technical documentation Chapter 2 describes career paths and documentation management styles Chapter 3 describes the precepts of technical documentation and provides examples of applying those precepts This chapter also provides background information on CALS a strategy for moving from paper to electronic media Chapter 4 describes the practices for gathering information understanding what you have gathered and meth
27. ve found and included all possible error messages Your technical resources must help with this task by providing you with a complete list of error messages but you are the one who must verify the completeness of your document Usability A usable document is one your reader can use easily it is not too bulky or designed in such a way that your reader must work extra hard to find the information Usability applies both to printed books and online texts The organization of your information is important too If you don t organize your information so that your reader can grasp the information quickly you will only frustrate your reader Your reviewers can help you find out if your document is usable more on these topics in Chapter 4 Usability tests help you determine if you have created a usable document and show you how to correct faults in documents that are less than usable Usability tests also help you analyze the effectiveness of the information you provide When people began to write technical documentation they practiced their art intuitively the work was essentially a craft As we have gained more expe rience we have learned more about the effectiveness of technical communica tion and have developed analytical methods to examine and test documents Technical Documentation Defined Usability tests properly applied can be extremely effective If you conduct such tests and modify your information accordingly you will find th
28. word painting both the work the artist performs painting and the result of the artist s work the painting In the context of this book technical documentation is any written mate rial about computers that is based on fact organized on scientific and logical principles and written for a specific purpose When you write technical doc uments about computers the subject you write about has a technical nature and you write with a specific purpose The scientific and logical principles you follow are To substantiate or be able to substantiate the statements you write To develop your ideas logically This is a narrower definition than that of technical writing whose defini tion is still developing Some suggest for example that technical writing is writing for a purpose while others suggest that it is a language a social group has agreed is useful All technical documentation is nonfiction though sometimes you may feel you are writing fiction and all technical documentation has techni cal content whether the purpose of the piece is reportage instruction or persuasion According to Webster s Ninth New Collegiate Dictionary the term nonfiction appeared only in 1909 Technical documentation is even newer Newspaper articles magazine articles and biographies for example being based on fact are all nonfiction but such literature is not technical documentation How ever a newspaper article can be technical docume
29. you will need to update your book when you think about packaging Quality in Technical Documentation 7 Further Reading You can explore the quality elements of technical documentation by reading The Elements of Style third edition Strunk and White 1979 and a good style guide you will find several listed at the end of Chapter 3 You can also gain an appreci ation for a variety of styles in English prose by reading The Reader over Your Shoulder Graves and Hodge 1964 or Language in Action or Language in Thought and Action Hayakawa 1941 1978 For More Ideas Some popular books and articles on scientific or technical subjects can also help you understand the subtle elements of high quality writing you can use in your work Examples include The New Physics Taylor 1972 articles in Science News and Scientific American and the works of Martin Gardner Popular Mechanics is another good source for clearly written technical articles Technical Documentation Defined A Career in Technical Documentation 2 A scribe whose hand moves as fast as the mouth that s a scribe for you Sumerian proverb c 2400 s c translated by Edmund Gordon cited by S N Kramer in The Sumerians TIP To give you an idea of what technical writers do these next paragraphs pro vide scenes of the kind of day many writers have The names and projects are purely fictitious Larry the Documentation Project Leader Larry Leader has been a write
Download Pdf Manuals
Related Search