specifications they get from the business analyst? If not, maybe your documentation isn't properly bridging the gaps between requirements, construction, and testing. In this week's column, Karl Wiegers explains that one should write documents from the perspective of the downstream consumers of the information, not from the author's point of view.
It's not unusual for a well-meaning requirements analyst to carefully prepare a software requirements specification and deliver it to the development team and testers, only to have the recipients gripe about it. Here are some typical complaints:
- "This doesn't contain enough detail. Now I have to do the analyst's job and chase down this information, or I have to make my best guess."
- "There's too much detail in the requirements. I didn't need all this information, just a general idea. I already know what to build. I don't even have time to read it. In fact, I don't think I will."
- "This document contains too much design information. The analyst is trying to do the design job I'm supposed to do. These so-called 'requirements' have eliminated my creative options."
- "This document isn't organized in a way that makes sense to me. I can't find the information I need."
- "There's a lot of text in here, but I have a hard time figuring out exactly what the requirements are. I have to wade through all the descriptive text and background information in each big paragraph and hope I'm interpreting the requirement itself correctly. I can't even tell just how many requirements there are."
Software project team members create various bridging documents, such as a software requirements specification (SRS). These documents are used to communicate information to other people so they can perform their parts of the project work. That is, these documents bridge the work that one community does to the work performed by another group.
The authors of these bridging documents typically write from their own points of view. The author selects in good faith the information to include, and he writes and organizes it in a way that makes sense from his perspective. But that isn't necessarily the perspective that will make the most sense to the reader. That can make a developer unhappy when the SRS flies over the wall from the requirements analyst and lands on his head.
I think we should write each bridging document from the perspective of the document's consumers-the downstream users of the document-rather than from the author's point of view. The requirements analyst should work with developers, testers, project managers, and others who will have to use the specification to determine how best to write and structure it. The consumers of the document are an important source of input regarding what information to include, how to organize it, writing style, and the appropriate level of detail. Working together to define the document's structure and contents reflects a collaborative approach to requirements development.
I encountered a bridging document problem recently at a telephone company I was working with. This organization has many business analysts who create requirements specifications that they hand off to their project's system architects. An architect complained to me that the SRS documents he received didn't always meet his needs. Sometimes, it seemed as though the business analyst already had done a lot of the high-level design, which the architect considered his own responsibility. In other situations, the requirements were primarily written at the user requirements level. The architect then had to derive the necessary functional requirements himself. He regarded this as being the analyst's responsibility, not his.
This is a classic situation in which the architects and business analysts needed to sit down together and agree on what information should go into the SRS. The business analysts at this organization were doing their best to supply the information they thought the architects needed at the right level of detail. Some additional input from the architects to guide the analysts' efforts would go a long way toward ensuring that future specifications properly bridged the gap between requirements development and software design.
I advocate a user-centric and usage-centric perspective to developing requirements specifications. Experience has taught me that looking at software systems from the perspective of the user, rather than that of the designer, leads to superior results. The same is true of an SRS and other bridging documents. By having the work product's consumers think about how they will use those documents and what information they need to do a good job, the authors and consumers can agree on templates and conventions for producing such documents. For instance, designers or testers might find it valuable to have certain information presented visually rather than in the form of natural language text, which probably would be the analyst's initial inclination.
Note that I'm not suggesting you create more requirements documentation. I'm merely proposing that the analysts, developers, and other stakeholders put their heads together to decide how best to prepare the requirements specifications they do create. Focusing on the appropriate content actually can lead to shorter documents, because the authors have a clearer understanding of what to include and what to leave out. The same principle of agreeing on form and content applies to design documents, project plans, and other project deliverables targeted at specific readers.
Rule number one for any author is "Know your audience." This applies to software project documents as well.
