Writing Requirements Documentation for Multiple Audiences

[article]
Summary:

When writing requirements documentation it's important to consider your audience. In this article, the author shows you what questions to ask yourself when you're preparing your project plan.

I mentioned to a friend of mine that I didn't think I had ever written a document with only one audience. Her response was that a document should never have more than one audience; that is, the only audience a document should have is the group of people the document is intended for. She stated that others may use the document, but they are not the audience the document is written for. While I see her point, I respectfully disagree with her assessment. Good technical writing has to focus on its audience's needs. For me, an audience is a group of people with similar needs and similar levels of technical and subject matter expertise and who will be using the document. Therefore, a software configuration management plan has many audiences: regulatory auditors with very little technical expertise, project team developing the system, extra-departmental IT support, and developers who will maintain the system five years from now. Therefore, once I am asked to write a document, I start by identifying my audience's needs and ask myself the following questions before I begin writing:

Who will use this document?
How will each audience use this document?
What information does each audience need in this document for them to use it?

During this discussion, I will use the requirements document as my primary example of how these concepts apply.

Who Will Use This Document?
Contrary to popular opinion, the first question you must ask yourself is not "What is the purpose of this document?" The first thing you must ask yourself is "Who will use this document?" The people who use a given document often span different roles in the organization. These roles can be departmental managers, developers, production line staff, etc. These roles in the organization have corresponding roles in each project, such as: management, project team member, and end user. Each of the roles can be considered a different audience because the people in each role have different levels of technical knowledge, subject matter knowledge, and uses for the document. To identify your audience, you, the writer, must ask yourself these types of questions:

Whose job tasks are defined by this document?
Who needs to review or approve this document?
Who uses this document in presentations?
Who is responsible for ensuring that project documentation meets your company's standards?

These people comprise your audience. In the case of the requirements document, the answers can be the project team, departmental management, subject matter experts (SME), and, especially in regulatory environments, quality auditors. Some organizations may have additional audiences, others may have fewer. The project team's job tasks are defined by the requirements document. As a result, the project team will design, develop, and test the system based on what the requirements document indicates the system should do.

Both the departmental management and subject matter experts (SMEs) review and/or approve the requirements document. Often the managers will use the document in presentations to senior staff and to other departments (such as internal customers or sales/marketing staff), while SMEs make presentations to users who are interested in how the system will meet their needs.

Finally, the auditors will review the requirements document to ensure the requirements document meets the company's standards for requirements documents (e.g., the requirements document contains all the information about each requirement the company wants) and to ensure the system does what the project team claims it does.

How Will Each Audience Use This Document?
The next obvious question is "What does the audience need in this document to use it?" To answer this question, you must ask yourself "How will each audience use this document?" The meta-purpose of your document is determined when you decide which document you are writing. Requirements documents have a different meta-purpose than a project plan; the requirements document describes the system functions and features, while the project plan explains the teams' approach and schedule for developing the software.

In the end, each audience determines exactly how they will use your document. The project team uses the requirements document to tell them what the system should do (the classic idea of a requirements document' purpose). In addition, the requirements document often serves as the linchpin for other documents, such as the design document, testing documentation, and configuration management documentation.

In addition to reviewing/approving the requirements for a system built in their department, departmental managers use the requirements document to gain support for the system. Therefore, the managers must be able to demonstrate the value of the system to its users. This value helps justify the expense of associated with the man-hours spent developing the system, the cost of new hardware or software, and explains to the customer why they should use the new system. In many ways, explaining to the customer why they should use the new system can be the most important support, for without customer buy-in, the system, no matter how well developed, is doomed to fail through lack of user acceptance.

The SMEs use the requirements document very differently than either the project team or the departmental management. While the SME does provide information about what the user needs, they also use the requirements document to tell the user how the software will meet their needs. In this way, the SME solicits feedback regarding the system and gains the user's buy-in and thus provide an informal, if not a formal, review/approval of system requirements documents to ensure they are complete.

Finally, the quality auditors use the requirements document to determine what the system does. Then, with the requirements as a starting point, the quality auditors will ensure that the design encompasses all the requirements, that all requirements are accounted for in the testing, and that the testing proves the code does what is required.

What Information Does Each Audience Need in This Document for Them to Use It?
Now you can ask yourself "What information does each audience in this document to use it?" The document must provide sufficient information for the audience to use it. Therefore, you must determine what knowledge each audience has and what additional information each audience needs in the document. When working on software systems, we need to determine what our audiences know in terms of technological knowledge and subject matter knowledge.

The project team should have a high level of technical knowledge; otherwise, they would not be creating the system. However, the team may not have much knowledge of the subject matter area. Therefore, we must include enough explanation, either in the requirement or in an introduction, to ensure that the project team will understand how their system is expected to perform the functions specified in the requirements. If the requirements specify that the system should perform date searches, describing the valid date range, the type of input, and what records to search will make the requirement more easily designed and tested.

Departmental managers have some technological knowledge because they are managers in an IT department, but we can not expect them to have in-depth knowledge of the newest changes in IT technology. However, they usually will not have much knowledge of the subject matter area. As a result, we must provide enough description of the subject matter and enough explanation of the technological decisions to enable the managers to evaluate and approve the solution and to enable them to discuss the value of the system to senior staff and managers outside the department.

The SMEs have an in-depth knowledge of the subject, but have a limited understanding of the computer technology to be used in the system. Therefore, we must include a description and discussion of the technological information so the SMEs will be able to evaluate and approve the solution proposed and so they will be able to explain to the end users that the system will meet their needs (and ideally be an improvement over their current solution, if one exists). Many times all that is needed is reducing the amount of "techie" jargon that is used and increasing the amount of "plain English."

If the requirements specify that the system should perform keyword searches on the load field, stating that the system will search within the load field for a word or a phrase will make the requirement more easily understood and applied by the SME. The quality auditors have a limited understanding of both the computer technology to be used in the system and of the subject matter. So, sufficient detail of both the computer technology to be used in the system and the subject matter will have to be included for the auditors to evaluate the efficacy of the requirements document.

Because the key to writing good technical documentation is meeting your audience's needs, returning to these questions on each revision of the document ensures that the document continues to remain relevant to the project.

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.