Encyclopedia of Computer Science and Technology

technical writing 471Further ReadingBest Free Technical Support Sites. Available online. URL: http://www.techsupportalert.com/best_free_tech_support_sites.htm. Accessed August 22, 2007.Czegel, Barbara. Help Desk Practitioner’s Handbook. New York:Wiley, 1999.Fleischer, Joe, and Brendan Read. The Complete Guide to CustomerSupport: How to Turn Technical Assistance into a ProfitableRelationship. New York: CMP Books, 2002.Tourniaire, Françoise, and Richard Farrell. The Art of SoftwareSupport: Design & Operation of Support Centers and HelpDesks. Upper Saddle River, N.J.: Prentice Hall, 1997.Tyman, Dan. “Tech Nightmares: Customer Service.” CNETReviews, January 24, 2005. Available online. URL: http://reviews.cnet.com/4520-10168_7-5621441-1.html. AccessedAugust 22, 2007.technical writingUsers of complex systems require a variety of instructionaland reference materials, which are produced by technicalwriters and editors. (It should be noted that technical writingcovers many areas other than computer software andsystems. However, it is the latter that fall within the scopeof this book.)The traditional products produced by technical writersin the computer industry can be divided into three broadcategories: software manuals, trade books, and in-housedocumentation for developers.Software ManualsUntil the mid-1990s, just about every significant softwareproduct came with a manual (or a set of manuals). A typicalmanual might include an overview of the program, anintroductory tutorial, and a complete, detailed referenceguide to all commands or functions.In theory, staff technical writers (or sometimes contractors)develop the manuals during the time the program isbeing written. They have access to the programmers forasking questions about the program’s operation, and theyreceive updates from the developers that describe changesor added features. In practice, however, writers may notbe assigned to a project until the program is almost done.The programmers, who are under deadline pressure, maynot be very communicative, and the writers may have tomake their best guess about some matters. The result canbe a manual that is no longer “in synch” with the program’sactual feature set.Technical writers often work in a publications departmentwith other professionals including editors, desktoppublishers, and graphics specialists. While manuals can bewritten using an ordinary word processing program, manydepartments use programs such as FrameMaker that aredesigned for the production and management of complexdocuments.In recent years, many software manufacturers havestopped including printed user manuals with their packages,or include only slim “Getting Started” manuals. Asa money-saving measure the traditional documentation isoften replaced by a PDF (Adobe Portable Document Format)document on the CD. There is also a greater relianceon extensive on-line help, using either a Windows orMacintosh-specific format or the HTML format that is thelingua franca of the World Wide Web. (See documentation,user.)Technical writers have thus had to learn how to constructHelp files in these various formats (see authoringsystems, help systems, and html). Creation of interactivetutorials also requires knowledge of multimedia formatsand even animation (such as Flash).Trade BooksAs millions of people became new computer users duringthe 1980s, a thriving computer book publishing industryoffered users a more user-friendly approach than that usuallyprovided in the manuals issued by the software companies.The “Dummies” books, offering bite-sized servingsof information written in a breezy style and accompaniedby cartoons, eventually spread beyond computers into hundredsof other fields and the format was then copied byother publishers. Publishers such as Sams, Coriolis, and particularlyO’Reilly have aimed their offerings at more experiencedusers, programmers, and multimedia developers.Computer trade books are often written by experienceddevelopers and systems programmers who can offeradvanced knowledge and “tips and tricks” to their lessexperienced colleagues. Since many technical “gurus” arenot experienced writers, the best results often come fromcollaboration between the expert and an experienced technicalwriter and/or editor who can review the material forcompleteness, organization, and clarity.In recent years there has been some contraction inthe computer book industry. This has arisen from severalsources: improved on-line help included in products; thedominance of many applications areas by a handful of products;and fewer people needing beginner-level instruction.In-House DocumentationMany technical writers work within software companies orin the information systems departments of other corporations,universities, or government agencies. Their work isgenerally more highly structured than that of the manualor book writer. As part of a development team, a technicalwriter may be in charge of creating documentation describingthe data structures, classes, and functions within theprogram. This task is aided by a variety of tools includingfacilities for extracting such information automatically fromC++ or Java programs. The writer may also be responsible formaintaining logs that show each change or addition made tothe program during each compiled version or “build.”This type of technical writing requires detailed knowledgeof operating systems, programming languages,software development tools, and software engineeringmethodology. It also requires the ability to work well aspart of a team, often under conditions of high pressure.Technical Writing as a ProfessionUntil the 1980s, few institutions offered degrees in technicalwriting. Programmers with an interest in writing orwriters with a technical bent entered the field informally.