Editing+for+Software+Documentation


 * CHAPTER 20: EDITING SOFTWARE DOCUMENTATION**

20.4 Types of Software Documentation
> ==20.4.1 Tutorials== > ==20.4.2 Procedures== > ==20.4.3 References==

20.5 Concerns In Software Editing
> ==20.5.1 Working With Programmers== > ==20.5.2 Short Turnaround Times and Version Control== > ==20.5.3 Electronic Help Files==

=20.1 DEFINITION OF SOFTWARE WRITING=

Software documentation writing is a form of instructional writing that accompanies a software product, and teaches a user to achieve proficiency with that product (Barker xxii). Broadly, software documentation writing is no different than most other documentation writing; technical writers must work with engineers to understand how the product works, and they must then design and implement a manual. The editing process is also similar.

However, some critical distinctions do exist. The purpose of this chapter is to illustrate those distinctions—and to explore how the challenges that they pose can be overcome.


 * FIG. 20.1.** A technical manual for the legal database software, ProLaw.

=20.2 WRITING FOR LAY AUDIENCES=

When computers were new, and those who used them were programmers, scientists, or other highly skilled professionals, software documentation—by necessity—addressed those advanced audiences. However, nearly everyone owns a personal computer in 2010, so the readers of software manuals are often now laypeople.

Modern software writers simply cannot assume that their audiences possess prior knowledge, and technical editors (who serve as reader advocates) must also be aware of this shift. Revisions may be necessary in order to produce documentation that lay audiences can understand.

In Designing Software Documentation, Thomas Barker notes that researchers attacked the problem of how to write for lay audiences by working in disciplines ranging from cognitive psychology to ergonomics to rhetoric (Barker xx11). Their objective was to develop a writing strategy that could instruct readers without prior knowledge. To fully describe such a strategy would be beyond the scope of this chapter, but one aspect is particularly relevant here: task-orientation.

=20.3 TASK ORIENTATION=

Task-oriented writing is a form of instructional writing that is organized according to the tasks a user will perform (Barker 4). An understanding of task orientation is critical to any discussion of software writing or editing because task orientation is the primary strategy behind modern software documentation.

Barker writes that: > Of all the innovations that sprang from the rapid rise of computer and software technology during the 1980s and 1990s, task orientation has provided the most dependable and useful tool for manual design. (Barker xxii)

What is the difference between task-oriented documentation writing and traditional documentation writing in practice? In short, traditional documentation writing does not concern itself with the needs of the reader. It simply lists information in order. A writer using the traditional strategy to document a menu in Photoshop would simply list the menu’s functions.

Conversely, a writer using a task-oriented strategy to document a menu would first perform a user analysis to determine what tasks his audiences performed with the menu. Instead of simply listing functions, the writer would describe how to accomplish each task. See Table 20.1 for an example:


 * TABLE 20.1**
 * ~ User Goal ||~ Traditional Strategy ||~ Task-Oriented Strategy ||
 * < Learn to use the mask editor in Photoshop ||< Describe the functions of the menu that contains the mask editor tool in order ||< Provide step-by-step instructions on using the mask editor to create a new layer. ||

=20.4 TYPES OF SOFTWARE DOCUMENTATION=

This section describes the three main types of modern software documentation: tutorials, procedures and references. While reading the section, remember that all three types of documentation are meant to be implemented with the principles of task-orientation firmly in mind. Quite often, it is the editor’s job to ensure that such a writing strategy is carried out.

=20.4.1 Tutorials=

Tutorials are a form of instructional writing that seeks to teach a user about a topic—either by demonstrating the topic, or by allowing the user to experiment (Barker 4). Although tutorials are traditionally associated with beginners, they can also serve advanced users.


 * FIG. 20.2**. A Microsoft Works tutorial. This one is a quickstart guide that shows how to edit cells.

In software documentation, there are five types of tutorial (Barker 34-38):
 * Guided Tours - Provide an overview of an application, focusing on main features.
 * Demonstrations - Describe specific features and user actions by running a limited-use version of the software that the user can observe.
 * Quick Starts – Assume more advanced knowledge then other kinds of tutorials. Provide a jump-in point for users who know what they want to accomplish.
 * Guided Explorations – Also provide a limited-use version of the software, but allow the user to ‘experiment’ with different functions, while providing feedback.
 * Instruction Manuals – The most traditional kind of tutorial; provide a linear series of instructions that teach the user to perform specific tasks

=20.4.2 Procedures=

Tutorials provide step-by-step instructions on accomplishing specific tasks. If tutorials seek to teach, procedures seek to guide (Barker 63). In Designing Software Documentation, Barker notes the following: “Guidance means that the user temporarily forfeits a certain amount of control to the manual or help system in order to get help in performing a discrete task” (Barker 63).

In software documentation, there are four types of procedures (Barker 73-79):
 * Standard – Often seen in software help files, this format aligns elements on the left, in either one or two columns, and lists procedure steps in numeric order, with each step on a new line. See Figure 1 for an example.
 * Prose – Using a conversational, relaxed tone, this format places steps in a series of paragraphs, often bolding user actions.
 * Parallel – This format is often used in software writing when users must fill out a series of fields in a form. It treats a series of items as one task.
 * Embedded Help – Provides context-sensitive assistance, depending upon where the user is in the program


 * FIG. 20.3**. A standard set of procedures for performing a spell check in Microsoft Word.

=20.4.3 References=

References contain information that will be looked up, as opposed to presented. Therefore, references are the least task-oriented form of documentation writing. However, they are often used in concert with procedures or tutorials, so that the overall manual delivers some knowledge in a task-oriented fashion, but also allows the reader to dig deeper as necessary.

Barker notes that references are often—although not always—the domain of advanced users (Barker 92). If tutorials are for teaching users, and procedures are for guiding them, references are for providing support (Barker 92).

Three types of references are used in software documentation writing (Barker 93-97):
 * Appendices – In software manuals, appendices often contain detailed technical information that might over-complicate other sections. Error messages, FAQs, troubleshooting tips, and shortcut key lists are some good examples.
 * Readme Files – Usually included with a program as a text file (and traditionally named readme.txt), readme files often contain last-minute additions or changes, bug notes, or installation tips.
 * Job Aids – These documents provide as-needed quick references for useful information. Not intended to instruct the user, they instead offer keystroke lists or command summaries.


 * FIG. 20.4.** A job aid-style reference that contains keyboard shortcuts for Microsoft Excel.

=20.5 CONCERNS IN SOFTWARE EDITING=

As mentioned above, editing software documentation is broadly similar to other technical editing, but key differences exist. Differences are found in: the environment of the project itself, the speed at which documentation drafts evolve (and goes out of date), and the complexity in editing electronic documentation.

=20.5.1 Working With Programmers=

On one hand, working with programmers as a technical writer or editor is the same as working with any other Subject Matter Expert (SME). It requires interviewing technique, research ability, and patience. On the other hand, programmers often serve as technical writers during software development projects (Barker 276).

Since technical people often take an approach to writing that is not intuitive for readers, the technical editor’s role becomes doubly important here. Information that is factually correct may still need to be drastically reorganized, and given a task-oriented treatment. Typically, managerial editors (or those who perform managerial duties) are responsible for working with programmer / writers (Barker 276).

=20.5.2 Short Turnaround Times and Version Control=

Software applications typically develop on the fly, and their features are in constant flux until the end of production. Documentation, therefore, must also be fluid—since its accuracy is contingent upon the latest version of the application.

Because of the constant state of flux of both the application and the accompanying documentation, version control software is necessary (Barker 276). Implementation of version control software is the responsibility of the editor.

Many [|version control] applications exist. Some commonly used standards include:
 * [|CVS]
 * [|Subversion]
 * [|GIT]
 * [|Mercurial]

=20.5.3 Electronic Help Files=

Software manuals are delivered in electronic form with increasing frequency. Although electronic editing is covered in detail in Chapter 16, electronic help files are particularly relevant to the software editor’s job description, and will therefore be covered in this chapter.


 * FIG. 20.5.** A classic electronic help file; this one is for the legal database application, ProLaw.

Typically, electronic help files contain chunks of cross-referenced information. For example, a sub-topic on matter creation in the legal software, ProLaw, might be linked to an index item, a related topic about changing matter numbers, and a glossary term for “matter.” The need to verify cross-referenced material vastly complicates a copyeditor’s job, since much back-checking must be performed (Barker 282).

Editors who work with electronic help files must also perform usability testing. Do hyperlinks work? Does the left-hand topic pane refer reliably to each topic and sub-topic? Are images functional? Does the help file display reliably in all the standard resolutions? All of these tasks are the concern of the technical editor (Barker 276).

=WORKS CITED=

Barker, Thomas T. //Writing Software Documentation: A Task-Oriented Approach//. 2nd ed. New York: Pearson, 2003. Print.

Modern Language Association. //MLA Style Manual and Guide to Scholarly Publishing//. 3rd ed. New York: The Modern > Language Association of America, 2008. Print. > Rude, C. //Technical Editing//. 4th ed. New York: Pearson Longman, 2006. Print.

University of Chicago Press. //The Chicago Manual of Style//. 15th ed. Chicago: U of Chicago P, 2003. Print.