By David Dick, STC Associate Fellow and Washington, D.C., Chapter Member

Introduction

Short deadlines force project teams to quickly design, test, and release the product with little or no design documentation. If these documents are written, they generally are not well-written and are not comprehensive. The fact of the matter is that most project teams do not have enough staff to design the product, let alone write and manage documentation. This situation creates an ideal opportunity for technical writers to assist the project team in more ways than writing a user guide.

System Requirements Specification

Whether a project involves building a house, a bridge, or designing the next generation computer, it must satisfy somebody’s wants and needs. A system requirements specification (SRS) (also referred to as the software requirements specification) is a document that identifies the users’ (client’s) expectations of the product.

The SRS must be well-written and precise, without ambiguity, because the outcome of the product depends on it. A well-formed requirements document identifies a product’s functionality (a capability) that can be validated, solves a customer problem or achieves a customer objective, and qualified by measurable conditions and bounded by constraints. The IEEE Standard 830-1993, Recommended Practice for Software Requirements Specifications, is an ideal source for understanding good structure and layout, and provides templates for structuring the content.

Business analysts follow a process that involves meeting with system owners, users, and project stakeholders to identify the product’s context of use. The SRS forms a contractual agreement for design and performance of the product. The SRS provides a basis to estimate costs and scheduling, a baseline for verification and validation of requirements, and a basis for future enhancements of the finished product. That’s why it’s important for the system owners, users, and project stakeholders to work together to create the SRS; once it is approved, any and all changes must adhere to a process to control changes.

A project that has no SRS has no agreement for the design of the product, and no reference for the project team to follow. E-mails, meetings and telephone calls are no substitute for an SRS. Mistakes made collecting system requirements are the costliest. Failure to manage changes to requirements causes the project to spiral out of control and over budget.

Functional Requirements Specification

When the SRS is approved; the next step is to define the internal workings of the product. The Functional Requirements Specification (FRS) describes the calculations, technical details, data handling, processing and other specific functionality, all of which are supported by non-functional requirements that impose constraints on the design or implementation (such as performance requirements, security, quality standards, or design constraints).

The FRS describes the required behavior, which may come from organizational or business rules, or discovered through elicitation sessions with users, stakeholders, and other experts within the organization. A project without an FRS has no agreement for design of the required behavior of the product, and no resource for the project team to design the product. E-mails, meetings and telephone calls are no substitute for well-written FRS. The FRS must be updated when changes are approved to the SRS. And just as with the SRS, mistakes made in the functional requirements are the costliest.

Requirement Traceability Matrix (RTM)

According to Leffingwell and Widrig in Management Software Requirements, every project must have the ability to trace requirements artifacts through the stages of specification, architecture, design, implementation, and testing to assure quality software implementation. The ability to track these relationships and to analyze the impacts of changes form a key thread throughout many high-assurance software processes, particularly in life-critical medical products and business-or mission-critical activities.

Many project teams oppose creating the RTM because it takes time to write and effort to maintain, and brings no added value to the product—so they think. Allow me, if you will, to describe why the RTM is essential to every project.

The Requirement Traceability Matrix serves two purposes:

• Lists the requirements. Only by validating the product against the requirements can the project team verify that the product is delivered according to specification.
• Traces the origin of the requirements, and identify how they are satisfied; how they are tested; and what impact will result if they are changed.

Traceability matrices can be created using a variety of tools including requirements management software, databases, spreadsheets, or even with tables or hyperlinks in a word processor. It makes no difference what tool you choose to create the RTM, so long as it is well-written and maintained. Without a RTM the project team cannot verify that the requirements are met, and cannot identify affected system components when there is a requirements change, affected components allows the impact of requirements changes on the system to be determined, facilitating cost, benefit, and schedule determinations.

Design Document

When the FRS is approved, the next step is to create one or more design concepts. The Design Document communicates decisions (concepts) on how to create the product. Diagrams show how functions and features work, the connectivity of components and, if the design is for a software product, diagrams the user interface. Depending on the circumstances, approval of the design concept may be a pre-requisite before development begins. A well-written design document addresses the requirements stipulated in the system requirements specification and functional requirements specification, and how the design satisfies them. Scott Hackett writes in "How to Write an Effective Design Document" that the hardest part of writing a design document has nothing to do with the writing: the difficult part is working through the logical design before coding.

Test Plan

Every product should be thoroughly tested to verify and validate that it satisfies the requirements for which it is intended.

A test plan identifies the objectives, scope, approach, and focus of product testing. The process to prepare a test plan is a useful way for the project team to consider the efforts needed to verify and validate the acceptability of the product, and if it satisfies the requirements stipulated in the SRS and FRS. The test plan should be detailed enough to be useful, but not so thorough that no one outside the test group will read it.

Test plans should be written to cover the following types of testing:

• Integration testing is conducted to validate if the individual software modules (combined and tested as a group) function properly.
• Unit testing validates that a particular module of source code works properly.

User Acceptance Testing (UAT) is conducted to validate if modifications or additions satisfy requirements. In software development, UAT is one of the final stages of a project and will often occur before a client or customer accepts a new system.

Usability testing measures how well people can use some human-made object (such as a web page, a computer interface, a document, or a device) for its intended purpose, i.e. usability testing measures the usability of the object.

Without a test plan, people testing the product do not have guidelines for which features and functions to test and expected results. Allowing testers to “play with the product” or “try to break the product” is not a substitute for structured testing.

Test Report

A test report is written by the individuals who tested the product. It identifies the findings and recommendations to fix bugs and suggestions to correct product defects. The test report should be detailed enough to be useful, but not so thorough that no one outside the test group will understand it. The test report identifies the tests conducted (e.g. integration testing, unit testing, and user acceptance testing) and results.

Without a test report, the project team does not know what features and functions were tested and the results, and recommendations for correcting problems in order to qualify the product for delivery to market or implementation.

Meeting Minutes

Meeting minutes are the hallmark of a well-run meeting. They provide a record of date and time of the meeting, topics discussed, decisions, open issues and action items. Minutes provide useful information for people who did not attend the meeting and a written record of the proceedings for attendees. Meeting minutes should be written immediately at conclusion of the meeting while the information is still fresh in everybody’s mind, and then archived in a location that is accessible to members of the project team.
Without meeting minutes, the meeting has no record of discussions, decisions, open issues and action items.

Release Notes

Every product has new features and functions, system requirements, and installation instructions that users should be aware of. The best way to communicate the information is with Release Notes. There are many ways to deliver Release Notes: as a separate document, on the product’s packaging, etc.; software products that can be downloaded from the Internet should be presented on a separate Web page or on CD-ROM. Release notes contain specific information about a particular product version such as system requirements, installation, new features and functions, changes to the product or release, and contact information.

Without Release Notes, users do not know important information about the product that can make the difference between a simple installation or a disastrous upgrade. Release Notes are not a substitute for a user guide, and a user guide is not a substitute for Release Notes.

User Guides and Training Manuals

If the project team does not recognize the importance of documenting the product design, it will publish a user guide and training guide. The user guide and training manual instruct users on how to use the product, but they are written differently and serve different purposes.

A user guide provides information about how to use features and functions, procedures to perform a variety of tasks, and tips to solve common problems. The user guide might be delivered as PDF on CD-ROM, hard-copy, or as help files embedded in the application or system.

A training manual provides information on features and functions and exercises on how to perform a variety of tasks. The training manual may be more effective if delivered as classroom training, but a video might be an economical solution to classroom training or on CD-ROM for self-paced training.

To learn more about the distinctions of a user guide and training manual see The User Guide and the Training Manual: Learn to Write Both by Cathrine Whitaker.

David can be reached at davidjdick at yahoo dot com.