Encyclopedia of Computer Science and Technology

documentation, user 159In addition to the commented source code, externaldocumentation is usually provided. Design documents canrange from simple flowcharts or outlines to detailed specificationsof the program’s purpose, structure, and operations.Rather than being considered an afterthought, documentationhas been increasingly integrated into the practice ofsoftware engineering and the software development process.This practice became more prevalent during the 1960s and1970s when it became clear that programs were not onlybecoming larger and more complex, but also that significantprograms such as business accounting and inventory applicationswere likely to have to be maintained or revised forperhaps decades to come. (The lack of adequate documentationof date-related code in programs of this vintage becamean acute problem in the late 1990s. See y2k problem.)Documentation ToolsAs programmers began to look toward developing theircraft into a more comprehensive discipline, advocates ofstructured programming placed an increased emphasis notonly on proper commenting of code but on the developmentof tools that could automatically create certain kindsof documentation from the source code. For example, thereare utilities for C, C++, and Java (javadoc) that will extractinformation about class declarations or interfaces and formatthem into tables. Most software development environmentsnow include features that cross-reference “symbols”(named variables and other objects). The combination ofcomments and automatically generated documentation canhelp with maintaining the program as well as being helpfulfor creating developer and user manuals.While programmers retain considerable responsibilityfor coding standards and documentation, larger programmingstaffs typically have specialists who devote their fulltime to maintaining documentation. This includes the loggingof all program change requests and the resulting newdistributions or “patches,” the record of testing and retestingof program functions, the maintenance of a “versionhistory,” and coordinating with technical writers in theproduction of revised manuals.Further ReadingBarker, Thomas T. Writing Software Documentation: A Task-OrientedApproach. 2nd ed. New York: Longman, 2002.Goodliffe, Pete. Code Craft: The Practice of Writing Excellent Code.San Francisco: No Starch Press, 2007.Knuth, Donald E. Literate Programming. Stanford, Calif.: Centerfor the Study of Language and Information, 1992.Rüping, Andreas. Agile Documentation: A Pattern Guide to ProducingLightweight Documents for Software Projects. Hoboken,N.J.: Wiley, 2003.Society for Technical Communication. Available online. URL:http://www.stc.org/. Accessed July 9, 2007.documentation, userAs computing moved into the mainstream of offices andschools beginning in the 1980s and accelerating throughthe 1990s, the need to train millions of new computer usersspawned the technical publishing industry. In addition tothe manual that accompanied the software, third-partypublishers produced full-length books for beginners andadvanced users as well as “dictionaries” and reference manuals(see also technical writing). A popular program suchas WordPerfect or (today) Adobe Photoshop can easily fillseveral shelves in the computer section of a large bookstore.A number of publishers targeted particular audiencesand adopted distinctive styles. Perhaps the best known isthe IDG “Dummies” series, which eventually diversified itsofferings from computer-related titles to everything fromhome remodeling to investing. Berkeley, California, publisherPeachpit Press created particularly accessible introductionsfor Windows and Macintosh users. At the otherend of the spectrum, publishers Sams, Osborne, WaiteGroup, and Coriolis targeted the developer and “poweruser” community and the eclectic, erudite volumes fromO’Reilly grace the bookshelves of many UNIX users.Online DocumentationDuring the 1980s, the lack of a multitasking, window-basedoperating system limited the ability of programs to offerbuilt-in (or “online”) documentation. Traditionally, userscould press the F1 key to see a screen listing key commandsand other rudimentary help. However, both the Macintoshand Windows-based systems of the 1990s includedthe ability to incorporate a standardized, hypertext-basedhelp system in any program. Users could now search forhelp on various topics and scroll through it while keepingtheir main document in view. Another facility, the “wizard,”offered the ability to guide users step by step througha procedure.The growth of the use of the Web has provided a new avenuefor online help. Today many programs link users to theirWeb site for additional help. Even help files stored on theuser’s own hard drive are increasingly formatted in HTMLfor display through a Web browser. Additional sources ofhelp for some programs include training videos and animatedpresentations using programs such as PowerPoint.By the late 1990s, printed user manuals were becoming aless common component in software packages. (Instead, themanual was often provided as a file in the Adobe Acrobatformat, which reproduces the exact appearance of printedmaterial on the screen.) The computer trade book industryhas also declined somewhat, but the bookstore still offersplenty of alternatives for users who are more comfortablewith printed documentation.Further ReadingCasabona, Helen. “From Good to Great—The Finer Points of WritingUser Documentation.” www.stc.org/confproceed/1995/PDFs/PG437440.PDF. Accessed July 9, 2007.“How to Publish a Great User Manual.” Available online. URL:http://www.asktog.com/columns/017ManualWriting.html.Accessed July 9, 2007.Kukulska-Hulme, Agnes. Language and Communication: EssentialConcepts for User Interface and Documentation Design. NewYork: Oxford University Press, 1999.Online Technical Writing [textbook]. Available online. URL: http://www.io.com/~hcexres/textbook/acctoc.html. Accessed July 9,2007.