Bridging Documents

[article]
Summary:
Are your developers and testers happy with the requirements
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'

About the author

Karl E. Wiegers's picture Karl E. Wiegers

Karl Wiegers, Ph.D., is the Principal Consultant at Process Impact in Portland, Oregon, and the author of Software Requirements (Microsoft Press, 1999) and Creating a Software Engineering Culture (Dorset House, 1996). You can reach him at www.processimpact.com. You can find more than 35 of Karl's articles at www.processimpact.com/pubs.shtml

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

Sep 22
Oct 12
Nov 09
Nov 09