Writing Requirements Documentation for Multiple Audiences

[article]

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

AgileConnection is one of the growing communities of the TechWell network.

Featuring fresh, insightful stories, TechWell.com is the place to go for what is happening in software development and delivery.  Join the conversation now!