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

StickyMinds 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!

Upcoming Events

Nov 09
Nov 09
Apr 13
May 03