Should I Avoid Including Design Details in My Requirements Document?

Reader question:

There is an ongoing debate over elements in a requirements document that could also be considered design. For example, screen mock-ups, file layouts and content. Which belong in a requirement document and which don’t?

Doug’s answer:

The reader is correct in stating that this is in an ongoing debate and I’m going to weigh in on it with a view that is rapidly gaining consensus. In fact, it’s been changing my own view little by little over the last year or two.

It used to be that an analyst would sit and write documentation for some number of months or years and turn it over to another team for consumption. That team would read it and…yes I said they would read it….begin the complex process of design and construction. The design and construction team would ensure all “Ts” were crossed and “Is” were dotted by tracing their output back to the original requirements and things were grand.

The times are a-changing folks, and so is the line between requirements and design…

The fact of the matter is that the world is a-changing, folks. As the business analysis profession has grown over the last 35 years or so (slowly I might add) and the software development industry has grown as well (much faster I might add). Since the early days of documentation, several things have taken place that bring the reader’s argument to bear.

One such item is the advent of modeling using diagrams, in which the professional crafts an abstract view of the problem or solution domain. Many times, we currently use UML diagrams to perform these functions, but there are many models that do many things. This has brought to bear the ability to actually see the problem and the solution in graphical formats that enlighten the viewer in ways that mere words could not. The ability to diagram with better and better formats and tools has even led to new types of software, like inteGreat and Enterprise Architect which have merged dynamic text creation with dynamic modeling capabilities. This new generation of tools is extremely powerful and effectively merges the requirements and design worlds together, as well as they documentation that they produce.

Another item out there that is growing in importance is rapid prototyping, and this one is really changing the way in which analysts operate. The tools in this category are used to rapidly model site maps and wireframes of screens during the elicitation process and right in front of the stakeholders. The ability to capture information, work it into a solution and garner feedback about within a few minutes leads to a much more effectual requirement and earlier understanding of the problem and solution domain. It also highlights a major shift in the way people work, and this change is something that some old-school analyst practitioners of change are struggling to deal with…myself included.

I have always been a proponent of not “putting pictures in front of users” due to the fact that this practice leads to design of a solution and distracts the stakeholders from the “Whats” that the analyst should be capturing. Keep the users away from pictures and it’s easier to focus on the core topic at hand; problem solved. However, as I think I’ve mentioned before, the world’s a-changing folks! People are more and more familiar with visualizing their input streams as a result of mass media in today’s environment. It’s much more common place today to use some sort of visual as the basis of discussion and collaboration even in the most mundane affair. Consequently, there is also a shift in how much people read, especially that dry stuff we call requirements.

As analysts have begun to embrace new methods and technologies based on what works with stakeholders, the result has been a melding of requirements and design in both the discussion and the documentation. Is this a bad thing though? If the stakeholder and the analyst are able to understand and dissect a problem earlier in the cycle and more thoroughly in depth, then the possibility of defects is reduced and that of success is higher.

Now here’s my caveat. To make this type of stakeholder and analyst interaction happen and for it to be successful, the analyst MUST have the skills to manage the tendency to drift toward too much design detail and to keep the conversations on task. Does it make some people uncomfortable when the clear dividing line begins to blur between requirements and design? Sure! However the real question might not be where do the design-type requirements belong, but rather is whether the fact that there are clearer, more concise, less ambiguous requirements gathered earlier with less effort and better results BETTER for the project. The rest doesn’t really matter and us old-schoolers are going to have to manage conversations in new ways to allow this to happen. We’re also going to have to realize that the world is a-changin’ folks.

>>Update Your Skills for this “A-Changing” World

Would you like a starting point for approaching common business analyst work scenarios in a more streamlined and visually-oriented way? Check out the Business Analyst Template Toolkit – all of the requirements templates are fully annotated and editable by you, giving you a great starting point for starting your next business analyst project or formalizing your work samples.

Click here to learn more about the BA Template Toolkit

Free Training - Quick Start to Success

(Stop the frustration and earn the respect
you deserve as a business analyst.)

Click here to learn more

By signing up, you agree to our Privacy Policy.

Comments

  1. Hey Bob:

    You actually bring up a good point that I neglected to mention. Many times when analysts include prototypes or wire frames in requirements documentation and the requirement go forward for sign-off, all of a sudden the visuals that were included ALSO become part of the approval process. When I have let this happen, it’s really been about me forgetting to separate the two or ensure that there was clear indication of DRAFT status. It’s important to note that the reqs may being undergoing approval, but the visuals are REPRESENTATIONS of what MIGHT be implemented, not factual entities. That is truly what design is for, to shake out the kinks of draft visuals and to make them work as real objects of use.

  2. I think this is a tricky problem because there are some very legitimate UI needs that SHOULD be expressed as requirements (which, to me, means they should be confirmed by some sort of associated test case, or validation step). An example might be that an authenticated user has single-click access (from anywhere in the application) to three key functional modes. This could be recorded in terms of a “story” about using a universal navigation widget, or it could be a non-functional requirement about navigability, or something else. In the course of eliciting or documenting the requirement, one might develop a sketch to discuss the idea, but the sketch isn’t a requirement.

  3. I also agree with Doug on this one. Mock-ups and other visual representations have been amongst my most powerful techniques for validating the requirements. So often users will catch things they see on the screen, but if I presented the information in a written form they would not even think to mention them.

    Dave, great point on drawing the line between what’s baselined and not. In most cases, visual representations of the requirements should be a validation tool and not a change control tool. There are exceptions of course (aren’t there always!). For example I’ve worked on some public-facing products where the visual renderings were provided in a formalized way and where very much “required” in the sense that the overall style, colors, look, feel, and navigation were integral to a successful implementation.

  4. Dave Schrenk says:

    I agree with Doug and see no issue with using screen mockups, wireframes, or any other type of diagram (that used to be the realm of the designers) to help elicit better requirements and including them in the requirements document. But, you have to be careful to make sure that everyone understands that, when it comes time to validate and baseline the requirements, it is only the requirements (the “what”) that are baselined. The designers / developers might find better solutions (the “how”) than what was documented in the screen mockups, wireframes, or other diagrams that you may have created and this should not result in the need to follow a change control process as long as the underlying “what” has not changed. Another alternative that I have seen once or twice is to combine the requirements and design phases. Neither are baselined until both are considered complete.