Perspectives on Software Documentation

Inquiries and Innovations

Thomas Barker, Thomas T Barker

• Publisher: Routledge
• Year: 2020
• Print ISBN: 9780895030696
• eBook ISBN: 9781351842310
• Topic: Business
• Subtopic: Law Theory & Practice
• Index: Business

This book is designed to address the randomness of the literature on software documentation. As anyone interested in software documentation is aware, the field is highly synthetic; information about software documentation may be found in engineering, computer science training, technical communication, management, education and so on. "Perspectives on Software Documentation" contains a variety of perspectives, all tied together by the shared need to make software products more usable.

PART 1

Inquiries

Chapter 1

Prologue for Teaching Software Documentation

Henrietta Nickels Shirk

OVERVIEW

The emergence of professional writers who document computer systems is a phenomenon of the last two decades. During this period, the development of software applications has experienced extremely rapid growth. There is a continuing need for well-trained, competent writers to document computer software applications for users of these products.

In the late 1960s and early 1970s, many people became software documenters quite by accident. They were either technicians who could (or were forced to) write, or they were people trained in the humanities who were hired by software development organizations because they could write and were able to assimilate the required technical information. With the development of more software applications for nontechnicians, software companies gave increased attention to their documentation as an important component for marketing their products and for establishing a satisfied customer base. The need for better trained “professional” software documenters has not only rapidly escalated, but academic degrees, certificates, and company training programs for training them have proliferated.

The training of software documenters requires attention to quality and consistency. The purpose of this chapter is to establish a foundation of assumptions and information necessary for the effective teaching of software documentation. It begins with a look at the genres of products which comprise the field of software documentation, defining the terms and briefly examining the steps which are the foundations of the software systems development and the publications cycles and their relationship. There follows an analysis of some of the different organizational structures both within software development environments and within software publications groups. From this foundation are suggested several instructional methods appropriate for teaching software documentation. Also analyzed are some of the issues surrounding the qualifications for both instructors and students who wish to successfully teach in, learn about, and work in the field of software documentation. Finally, some of the cultural assumptions in today’s software development environments regarding software technicians and documenters are described. The goal is to provide some suggestions for resolving several of the current conflicts between these two groups in the workplace. The chapter concludes with a brief look at possible changes in the future role of the software documenter. One must begin with the products themselves.

PRODUCTS

The products produced by software documenters cover a broad range of genres, each requiring different techniques and skills. Broadly speaking, one may divide these genres into two categories—internal and external information. Internal documents relate to the activities within software product development organizations, while external documents relate to the activities of the end users of the software. Some of the internal documents may be written by technical staff and edited by software documenters, although the software documenter may frequently have responsibility for all the documentation, both internal and external. While not every writer in the computer software industry writes every kind of software document possible, it is not uncommon for writers in smaller software development organizations to have responsibility for several of these types. Those in larger organizations tend to be more specialized, with responsibility for a single type of document.

Figure 1 presents categories of the major types of software documentation. It is important to note that the overlap between technical and nontechnical information is especially true regarding the content and audience for reference guides, which may be written for either technical or nontechnical audiences, depending on the software product. Complex software products typically include reference materials for advanced (and technically inclined) users. Quick reference cards are examples of documents prepared with very experienced users in mind and for software products with many complex instructions. This overlap may also occur in problem statements, which may be written by marketing personnel. Typically, they contain not only a nontechnical description of what the software product should look like (its features), but also an analysis of the product’s potential market (its audience).

Figure 1. Major types of software documentation.

Technical, internal documents are, in fact, among the source information available to software documenters for creating the nontechnical, external documents. Software documentation products do not exist as single unrelated components. Because they are all part of the same product, the success of one document is related to the success of all the others.

The following conceptual paradigm, which assists in clarifying one’s understanding of software documents, is the basis for all software code (see Figure 2). While technical, internal documents cover the whole software product, they tend to focus more intensely on the processing aspect of the software. It is, after all, the job of the technical staff (analysts and programmers) to assure that the software performs its intended functions. On the other hand, the nontechnical, external documents tend to focus on the inputs to and the outputs of the system. These are the most important concerns for the end user, who usually does not care about how the code processes the information put into the system. End users care more about knowing what is expected of them concerning the inputs and running of the system, and what they can expect in terms of output from the system.

Figure 2. Software paradigm.

Keeping the parts of the software paradigm in mind helps to focus on both the audience and general content of each type of software documentation. The descriptions of components of the two broad categories of software documentation follow.

Technical, Internal Documents

These documents cover a spectrum of products created to record the development of the software. These documents may be problem statements, which define the potential customer base for the product and the actions that the software will perform for this audience; and requirements definitions, which describe the general features of the product. There is an important group of documents generally labeled as specifications, which may range from general (or functional) descriptions of what the software will do, to more specific (or detailed) descriptions of file structures and computer processing routines. Broadly speaking, documentation in this category may also include system and programming diagrams and even comments within the code. A final group of documents may be generally identified as “project tracking” records. These are status reports on the progress of the design and coding and memos communicating changes made to earlier product specifications. All these technical, internal documents are not only required for the effective operation of the development strategy, but they are also important sources of information for creating end-user documents.

Nontechnical, External Documents

Nontechnical, external documents cover a broad spectrum and demonstrate the diversity of written materials within software documentation. They may range from encyclopedic or abbreviated reference guides to marketing brochures and advertising materials, such as data sheets and sales “leave-behinds.” At the core of this category, however, are the documents written for the nontechnical users. These are procedures, as well as educational materials, for group or individual training sessions on the software. These components may be traditionally “paper-based” (communicated in writing through the medium of paper), or they may be “computer-based” (communicated online through the medium of the computer screen). When online, they may cover everything from brief error messages to fully developed HELP systems to computer-based training sessions. However, all of the components of this category are focused on the inputs and outputs of the software, rather than on how the software processes the inputs or creates the outputs.

All of these software documentation products, whatever their category, are not only interdependent on each other but also result from several well-defined activities that occur in the environments of software development organizations. One must understand the processes that produce these products, in order to understand the products themselves.

Software and Publications Development Cycles

The products of software documentation are not created in a vacuum. They are the outcome of several interactive processes within organizational structures. The major interaction is between the software development cycle and the publications development cycle. This dualistic organizational paradigm is crucial to understanding the environmental milieu in which software documentation comes into existence. It should be taught as part of the required foundation of assumptions that software documenters must have as prerequisites for working within the software industry.

One might correctly ask why there are two processes rather than one. The two cycles exist in the software industry because they result in the production of two different aspects of software—the code and the documentation. Ideally, the two cycles should be merged, so that both parts of the product are ready for distribution at the same time: the ultimate accomplishment of successful software development organizations. In practice, however, there are usually several “lags” along the way between the creation of the code and the documents written for the end users. The goal for both cycles is to meet a final, single deadline.

The steps undertaken to produce software code and those to create the software documentation typically look like the parallel cycles outlined in Figure 3. Software technical writers need to understand thoroughly not only their own publications development cycle, but also that of the development of the code, so that they can monitor both cycles. Such an understanding can ease many of the frustrations that typically result in software development, because of the lack of direct synchronization between the two cycles. Most steps in both cycles are reiterative, causing numerous changes, until the final product is distributed and delivered. When those developing the system do not communicate these changes to those who are writing the documentation, breakdowns in communication between the two cycles frequently occur.

Figure 3. System development and publications cycles.

It is helpful to understand not only the content but also the similarities and relationships among the progression of steps in the two cycles. Without an understanding of these required parallel processes, neither of the two cycles will be totally successful. The success of one cycle depends on the success of the other.

ORGANIZATIONAL STRUCTURES

The second pair of concerns for software documenters is that of understanding the publications function in terms of its placement within organizational structures and in terms of its own internal organization. Without such an understanding, software documenters are apt to suffer unnecessary frustrations and thwarted career goals.

While organizational structures may differ from one software development environment to another, some common patterns, often called reporting structures, can be analyzed in terms of their advantages and disadvantages. The seven reporting structures described below represent the most frequently encountered locations for software publications groups within organizational hierarchies.

Marketing and/or Public Relations

The rationale for placing software publications groups within marketing and/or public relations functions is that all documentation helps sell software products. In all its forms, documentation is really a marke...

Table of contents

• Cover
• Title Page
• Copyright Page
• Acknowledgment
• Table of Contents
• Introduction: Research Sources in Software Documentation
• Part 1: Inquiries
• Part 2: Innovations
• Index
• Contributors