This article was originally published in the May 2008 issue (Vol 13, No. 3)

About the Author

Pradipto Das is a Senior Technical Communicator with Infosys Technologies Ltd., and a member of the India Chapter.

STC UUX Community Newsletter
Usability Interface

Making the Case for Explicit Documentation Requirements

By Pradipto Das

Clearly defined documentation requirements are instrumental in ensuring the appropriate documents are created accurately and in a timely manner. This article will make a case for using explicit documentation requirements and will recommend a method for putting it into practice.

Introduction and Terminology

A documentation requirement is a request made by marketing or engineering to document a particular feature of an application. The Technical Publication team can also request that a feature be documented. The request to document a feature is often detailed in a numbered paragraph in a document such as an SRS (System Requirement Specifications), an IPP (Integrated Project Plan), or a DPP (Documentation Development Plan), which describes the documentation impact of a software feature. Alternatively, there can be a request for a new manual in which a family of features for a new or existing product needs to be documented.

Explicit vs. Implicit Requirements

Historically, there have been two types of documentation requirements: explicit and implicit.

• Explicit documentation requirements are clearly described in the planning document, as stated above.
• Implicit documentation requirements are not formally recorded in a planning document, but are implied by new or modified software features.

To help ensure high quality documentation, it is always preferable to have explicit documentation requirements at or near the beginning of a product development cycle.

Methods of Gathering Documentation Requirements

At a high level, the Technical Publication group can generate documentation requirements themselves, or they can be generated by marketing or engineering.

When technical writers generate explicit documentation requirements, the writer or lead writer creates a list of documentation requirements from an SRS or IPP, or by exploring the application interface. Engineers may provide assistance, but the burden of requirements generation falls on the writer. This method has a number of disadvantages including:

• The writer may not understand the software features in the first place and, in these cases, they cannot ascertain the documentation impact.
• There are too many software features, or the source documents are made available too late, making it impossible for the writer to create the list of documentation requirements in the time available.
• Even when the writer understands the software features, the documentation impact may not be apparent, thus creating additional, unscheduled work for the writer when creating the documentation.
• The Technical Publication group may get a late start on documentation for a project because of prior commitments, and therefore does not have enough time to adequately gather documentation requirements.

When marketing or engineering generates explicit documentation requirements, the requirements for an application release are given to Technical Publication near the beginning of the application development cycle. For those applications that now follow this approach, it is typically the Program Manager who generates the list of documentation requirements, and the Engineering team takes on a larger role in documentation requirements generation. This method is preferred and has a number of significant advantages over the first method. Some of these advantages include:

• The writer needs Engineering input before writing can begin. This proposal formalizes that process.
• It takes much less time for Technical Publication team to scope the documentation work for a project because the technical content of the documentation requirement is already available.
• The writing takes less time because initial information is correct and complete.

Why Explicit Requirements Work Better

Explicit Documentation Requirements

Explicit documentation requirements from subject matter experts provide the following benefits:

1. Input from Engineers is needed to accurately estimate documentation impact: Engineers know the software features being added or changed in an application, and their input is needed to determine the documentation impact of these features. By relying on writers alone, many of whom cannot be as well versed in the design details as the developers, we risk misunderstanding a feature, or worse, not recognizing the full documentation impact of a feature. We also run the risk of not documenting a feature at all.
2. The documents will be much more accurate and complete: Because the documentation requirements are explicit and would go through a review process by engineering, marketing, and documentation, increases the likelihood of accurate, timely documentation delivery. Also, the writer could focus more time on writing the user documentation for the feature, thus ensuring greater accuracy.
3. The documents would take less time to write: The writer would not have to spend time generating the documentation requirements. Also, with mature, explicit requirements as a starting point, the documents would take less time to write, and would achieve a higher level of quality.
4. Overall document quality will increase: The Engineering team will be required to do this work at the feature definition stage, instead of near the end of the project, when the Technical writers start asking questions that should have been answered earlier in the product development cycle. The time spent by the Engineering team to support the documentation is reduced (and more focused), and the writers can concentrate on writing the documentation.
5. Uniformity in documentation requirements: The uniformity of documentation requirements with details of the features to be documented and their impact on users will help new writers be more productive within a short span of time, even if they are not familiar with the application.
6. The documentation team will be able to address more documentation requirements: The explicit documentation requirements will enable each writer to handle a greater number of documentation requirements. The ratio of engineers to technical writers is typically 8:1 or 10:1 at the most. With good requirements, this ratio can be optimized.

Implicit Documentation Requirements

The SRS descriptions of an application feature do not usually provide enough information for the writer to determine the documentation requirements. A typical example will demonstrate the difficulties the writer faces.

Consider the following example taken from an SRS:
"SRS_111: The template source file for the wizards will be updated to use new sources provided by Customer Engineering."

Although the meaning of this requirement might be obvious to the application engineer, the writer does not necessarily know what a "template source file for the wizards" is, nor what "sources provided by Customer Engineering" are. The writer is unable to assess whether there is a documentation impact stemming from this software requirement. If there is a documentation requirement, then it cannot be deduced. Ultimately, the implicit documentation requirement must be clarified by the Engineering team.

To provide more information on the impact of this feature on the user, the engineer could describe the possible benefit to the user. In this case, the benefit might be a statement as: "The user selects the template source file from the directory (such and such) when creating new source programs. Doing so will provide the following benefits during the programming process: (enumerated benefits)."

Without the appropriate level of detail, the writer has no idea whether this feature needs to be documented. It is not even clear which Engineering functional manager the writer would need to acquire additional information from as a subject matter expert. The writer expends precious time trying to gather basic information that should have been provided in the first place.

This example demonstrates that an explicit documentation requirement, generated by Engineering, is a necessity.

How to Capture Documentation Requirements

The following is a suggestion of how to capture documentation requirements:

1. Engineering produces a list of documentation requirements based on the SRS or IPP. Each requirement must conform to the standards specified for application development.
   What to include in document requirements:
   • The following methods can be used to capture and maintain documentation requirements for a given application:
   • The SRS (or IPP) numbers of the software features on which this requirement is based
   • A brief description of the feature from the user's point of view
   • The feature's impact on the user
   • The documentation impact at a very high level, if known
2. The documentation requirements provided by the Engineering team are incorporated by the Technical Publication into a DDP and assigned a DDP number.
3. The Engineering team must include the Technical Publication team at the various stages of the product development lifecycle, especially at the requirement gathering stage, as this will help the Technical Publication team to better understand the requirements and product changes.
4. All documentation requirements must be explicit and conform to a predetermined content format.
5. The Engineering team and the Technical Publication team conduct a Documentation Requirements Review Meeting after the SRS has been finalized and the documentation requirements have been provided to the Technical Publication group, but before technical writing begin. Documentation requirement reviews occur in the same way that SRS requirements are reviewed by the Engineering and Marketing teams. The Marketing team should participate in this review meeting to ensure that all documentation requirements are clearly understood and agreed upon. A "will do" or a "will not do" proposal is made for each documentation requirement based on the degree of difficulty and any resource limitations for the current release of the application.
6. Only explicit documentation requirements are addressed by the Technical Publication team.
7. At the meeting between the Engineering team and the Technical Publication team, the roadmap for the list of explicit documentation requirements and measures such as scheduled documentation reviews is designed.

Summary

Implicit documentation requirements work well to communicate minor changes (e.g. correct bugs in code, or correct typos on an online form) to a non-critical product. There's no justification and time to follow a process to formally gather requirements, and create/update a myriad of documents. Anything that slows down development and diverts efforts to time-consuming processes and creating a myriad of artifacts, allows more time to code and test the system.

However, when criticality of understanding requirements is essential to communicate major changes (e.g. redesign the billing process for a high-volume e-commerce website, or add new functions and features to a medical application) some requirements should be documented as a matter of record. Moreover, implicit requirements become a risk factor when a customer is not satisfied with the behavior of a particular function or feature, and asks to know why it was designed that way. Saying, "That's what you asked for. Don't you remember what we talked about?" may not be an appropriate answer for all situations, and may not win new business. By standardizing explicit documentation requirements, the project team is likely to see an increase in quality, accuracy, and timely delivery of its technical documents.