Read any Good Requirements Documents Lately?

Personally, I love reading requirements documents. I put them on my night stand right next to my last car loan contract and all the paperwork from my last home closing. They really do the stuff when it comes to insomnia, sure beats the prescriptions and the wacky side effects. But in all seriousness, let’s think about what these documents are and what they all have in common, (Besides being mind-numbingly boring to read).  All of these documents serve a purpose; the loan documents and title paperwork that we deal with in our personal lives are the standard that we refer to when questions arise. We’ve come to accept these documents and it’s a well known fact that we don’t read them and in many cases we can’t read them, at least not in an intelligible manner without our lawyers present.  Anyway, when was the last time you brought your lawyer to purchase a car? The fact of the matter is, we don’t.  We discuss the terms and assume that the person or organization we are doing business with is trust-worthy and while we might glance through the paperwork, ultimately we trust what was discussed and we sign blindly, and most of the time that works out OK.

So how does that differ from your stakeholders and requirements documents? Well in truth, it really doesn’t. The business (your customers) verbally or written in laymen’s terms explain what they would like: a new website, an update to the customer service app, integration with the new expense system, or any number of other projects. As analysts or project managers we then go off and decide what needs to be done to accomplish this goal; is it feasible (?), does it make sense (?), and if so what are the requirements? We then diligently begin our process of eliciting requirements from the stakeholders, the end users of the product, and any other interested or concerned party. A series of meetings is scheduled to review these during our validation phase and ultimately we create the beloved Requirements Document.  By this point, it truly becomes a document only an analyst or perhaps a lawyer could love. We’ve carefully crafted each line, diagram, and chart to clearly explain and account for each subtle nuance that the project requires, ensuring that we’ve taken the needs of the end users, the business and development constraints into account. We secretly admire the bulk of the document as the result of a lot of hard work. Some of us might even print a copy of it and prominently place it on our desks, hoping that our bosses will come by and be impressed by the sheer volume of our latest work. It’s our baby, or our latest masterpiece and we should be proud.

We then present this Requirements Document to our stakeholders who initiated the project and seek their approving signature. We discuss this in a meeting and the document is then presented for signing, but like our car purchasing analogy the document signing has become ceremonial. The stakeholder trusts that you understood the requirements and assumes that the signing is nothing more than a necessary step. But is it? Do they understand the constraints that development has placed on the project? Do they know that the end users requested a very different approach to the way the screens are configured? Just like buying a car or closing on a home, they give it a cursory glance, or perhaps hope that their team has read it in depth and would surely advise them if something was amiss. If this were the case why do the industry analysts consistently throw out numbers ranging from 20%-60% of each project budget is spent on re-work? The culprit is usually identified as poor requirements. Poor requirements? We worked for 8 weeks on that document, it was 160 pages long, we accounted for everything. How could we have ‘poor requirements’?

The answer is not poor requirements, but rather that once all parties were involved in the elicitation process the project began to change. With each new person giving their input to the requirements, it changed the goals and results of what the stakeholder had originally imagined when they first presented it to you. Given that they did not thoroughly read through the initial presented requirements document, they were not aware of what the new version of the project looked like. So development hosts the first review session of the product and the stakeholders are shocked.

“This is not what we contracted!” they say.

“But it’s all right here in the Requirements Document, you signed it.”

“Well it’s not what we wanted, it needs to be re-done.”

Start the re-work counter.

So, what can be done? Well many shops have switched to Agile to try and catch this a little sooner, and it can work well, but you still need defined requirements for the overall project and you need to understand what each sprint will entail (we still want successful sprints). Perhaps the problem is in the requirements process itself. Some have called for the “death of the requirements document”. In the near future, I don’t see the requirements document going away. It serves a purpose, but not to communicate requirements to stakeholders, just like the loan documents we sign don’t communicate the terms, of our loan, interest rates, or payments dates. There still needs to be a record of the work that is being performed, and there needs to be a form of acceptance.

What needs to change is how we present these requirements to our stakeholders; hosting visualization sessions, presenting mock-ups and wireframes with functionality built-in that give our stakeholders a real-world feel of the final requirements and how they may have evolved through the inputs of others. We might want to use process diagrams, use cases, or other tools to tell our story. The fact of the matter is we need to tell a story, not present a contractually binding document and hold our stakeholders feet to the fire when this goes wrong (we’ll save that for car salesman and realtors). Once this is understood through communication and we all agree on what it is we are embarking on. We can then, once and for all use the requirements document for what it is best suited for, a place to sign our name that signifies agreement amongst all parties before we drive off in our shiny new car, or take the keys to our new home, or begin development on that new much needed new application or update.

For unity's sake, clean up those requirements documents!!!

It's easy enough to tell a story, but what happens when the consumer's comprehension of the story determines how it will turn out. Imagine a book that automatically changes the ending based on the reader's understanding of what the author was attempting to say. Inevitably, no two readers would share the same ending. There would always be differences of opinions and the value of the story could be drastically reduced if the author wasn't extremely precise in what was written.

 The Business Analyst is an author and the ending to the story they write will vary based on how the story is understood. The Analyst sits between the Business Partner and the IT group, and authors a story based on what they understand the Business Partner to need. This story then gets handed to IT and their job is to go and write the ending. As we all know, in this type of story, the ending is rarely what the Business Partner or the Analyst expected.

Although there are many factors that contribute to an unhappy ending, I want to focus in on the topic of unity. As a parent I'm often looking at my kid's room and saying, "For goodness sake, they need to clean this room." When I look at most requirement documents I think, "For unity's sake, they need to clean up this document." Unity is what holds the story together and gives it a clear and precise context. Every story needs context in order for the reader to relate and connect. If the document feels like a scrambled jumble of parts and pieces, the reader will never connect with the story. If they don't connect, they can't provide the feedback that's so desperately needed before IT starts to write the ending.

To accomplish unity in a document you must do the following:

1) Always provide a consistent look, feel, and structure - a template
2) Leverage hyperlinks in the document so it's easy to navigate to related elements - easy navigation
3) Clearly identify how the different elements relate to each other - rich context

The reader needs to understand how a goal is accomplished (Use Cases), how each step used to accomplish the goal relates to the needs of the Business (Business Requirements) and the tasks of the users (User Requirements). How the system steps in the Use Case drive the System or Functional requirements. What UI Mockups should be used for a given step in the process, and so on. When all these different pieces are in unity throughout the document, then, and only then, can the Business Partner drive precision into the story, (via feedback) so that the IT Group can write the most accurate ending.

Although I agree with Chris Gurney's post, "The Big Freaking Document Must Die," until Analysts adopt better tools that help tell a more unified story, via visual simulation of requirements, or at least generate documents with unified content, we're stuck manually creating documents. But keep in mind, especially with manual documents, it's not just about having content, it's about unity of content. Content alone is useless, unified content is easily understood and opens the door to precision. And when the reader is writing the ending, precision is king.

So, for unity's sake, clean up those documents.

Requirements - What’s the big hurry if they are going to change or be wrong?

It always appears to be rush, rush, rush, never enough hours in the day to sit with the business folks, host a JAD session, document what they want, type it all up, print out the requirements document and send it to a sea of people to who approve something they probably just skimmed through and will ultimately change their minds on anyway.....after the code is written.

SLOW DOWN!!!

OK, if you are a pure Agile shop, don't spend too much time reading this, the sprint is finishing and that piece of functionality is still not working. At least in an Agile environment we embrace change and the customer is part of the team and we review and change all the time and the requirements are adequate being defined to the "just enough" level of detail, the minutia will be worked out by the team and the customer.

However, back in the rest of the world, we spend less and less time on requirements and are eager to throw it over the old wall to development that in turn may see an ambiguous or incomplete requirement and happily code what they think the BA intended. This is then sent down stream to QA who in turn also sees the gaps in the requirements but has a conversation with the developer to fill in those gaps....before you know it, 40% rework on your average project.

So what can we do about this......Ultimately, we need to actually spend MORE time in the requirements phase of a project. Not so that we can add pages and pages of more detail to the "Big Freaking Requirements Documents" but so that we can create more clear, concise, unambiguous requirements and iterate through the process and work with the business to validate these requirements BEFORE we hand off to development. I sell a requirements tool for a living and I often get the impression that people think that a Requirements Definition and Management (RDM) tool will make the requirements process faster when in fact it should make the process a little longer (Shock horror I hear, how could he say such a thing). Well it is true. Tools really focus us on completing a detailed set of requirements; they add traceability that can be used to show completeness. Use Cases (UC) can be used for detailed walk through and simulation of the requirements, showing Wireframe and UI Mockups of applications that we have not started to build as yet.

Believe me, stepping through a UC or a simulation in a room full of people or via a web session will produce you far more feedback than any 300 page requirements document that you stuck on Sharepoint and emailed the approval group and told them they have 1 week to review. So take the time to approach requirements slightly differently, let's get them right before we pass them on and propagate any misunderstanding downstream to Development, QA and the Customer.

You want defects in your Requirements Definition & Management Solution?

To clarify, the question above does not refer to bugs in the actual code of your RDM solution. The answer to that is obvious. Instead, it asks whether as users/practitioners, we would want or need to accommodate defects as an artifact type in our RDM solution in much the same fashion we do Business or Functional Requirements, Use Cases, Diagrams and other staples of requirements authoring. So, is it a good idea or not?

Traditionally, we've been conditioned to think of a defect as an issue or a problem with the software discovered by QA during the testing. It is formally documented and if it truly is a defect, it results in a change to the developer's code as a correction and the issue is re-tested in the next build and the defect report is closed out if addressed properly.

Early on in my software career, I noticed that developers were very sensitive (sometimes explosive) when confronted with a defect report against their code. Initially, I was surprised by the combative responses I received. Developers took a defect very personally. And why wouldn't they? Defects have an undeniably negative connotation and ultimately, developers know they will at some point be judged according to defect counts against their code.

But, it isn't just QA who finds and documents defects. They can come from anywhere in the SDLC and beyond. Other developers can find fault with someone else's code they need to work with. Issues can come in from the field as well, either from sales engineers, beta customers, or GA customers. Wherever they originate, they end up in the system of record and ultimately flow back to the offending developer.

However, focusing on defects as a pointer to bad code is too narrow a perspective. Often times, an issue is written up as an enhancement to existing code or new functionality all together; and again, these can come from various sources. Regardless, they all flow through a proscribed workflow where they are reviewed, categorized, assigned, and tracked all along the way with appropriate status. More often than not, these formalized "change requests" are the only source of meaningful metrics in a development organization.

In the same fashion that QA reviews compiled code, someone should also be reviewing requirements. When the business does this, we are looking for validation that we've captured the requirements completely and correctly. Architects, Designers, Developers, and Testers should also review the requirements as well. After all, they will be tasked with making these come to life in the form of an application or system.

If there are conflicts, inconsistencies, ambiguity, etc. shouldn't the various parties performing the reviews be noting these as change or enhancement requests and attaching or tracing to the offending items and authors? Like a defect against code, these change requests against requirements should be formally documented, categorized, and flow through a proscribed workflow where rationale, questions, comments, and action taken are captured along with the item's state.

This degree of formality doesn't take effect from the firing of the starter's pistol. Obviously, the people eliciting and documenting requirements need the flexibility and freedom to author, edit, and rearrange as they see fit without unnecessary overhead. However, at some point in the requirements process a line in the sand needs to be drawn. From that point forward, we should be tracking change more formally. Ultimately, it is about more comprehensive communication, from the initial request for change or clarification, through all the arguments for or against, and then the actual action taken or not taken as the request is closed out. This record is now available for all parties to consume and may actually work to prevent further requests for change. As with the developer, the collection of these change requests can be a useful tool in assessing the authors of our requirements.

Lastly, as with defects against code, these requirement change requests can originate anywhere in the SDLC and beyond. Therefore, they initially may be documented in other systems. However, the premise of my argument is that, whether we document within our RDM system directly or they automatically flow in via integrations to other SDLC solutions, we should formally accommodate them and pay attention to them.

So, yes Virginia, we do want defects in our RDM solution!

Big Freaken Requirements Documents Must Die!

 The typical requirements document is a long, sprawling piece of literature. Within it, one might find a title page, table of contents, change history, complex headers and footers, legalese, confidentiality notices, and, if you're lucky, maybe even requirements.

Its length is probably, primarily due to the fact that it tries to be everything to everybody. But, the problem is that this big freaking document isn't read entirely by any single person, except perhaps by the person who wrote it in the first place.

Every company refers to these documents as something different: BRDs, PRDs, BPDs, DRDs, SRSs, FRDs... or any other number of acronyms that people have forgotten the meaning of. OMG! To complicate matters, each department, project team... heck, person, uses their own template; so, one BRD does not necessarily equal another. But, who can blame the people that write these things? There are deadlines to be met, and all templates do not accommodate the needs of the many. Adjustments are made.

But luckily, from where I sit, I believe that the typical, mega-honking requirements document is nearing its death. And the good news is that this eventuality is closer than most people think. Don't believe me? We have actually witnessed this happening at some of the more progressive companies that we've worked with.

Let's walk through the reasons why I think these documents exist, and the problems that lie within.....

 

Click here to check out the entire article posted on Business Analyst Times!

Big Freaking Requirements Documents !

The typical requirements document is a long, sprawling piece of literature. Within it, one might find a title page, table of contents, change history, complex headers and footers, legalese, confidentiality notices, and, if you're lucky, maybe even requirements. It's length is probably due to the fact that it tries to be everything to everybody. But the problem is that the document isn't read entirely by any single person, except perhaps by the analyst who wrote it in the first place.

And parts of these documents are only relevant to certain people. High-level overview stuff is great for managers, but developers could care less about the project's "vision"; and testers only require certain parts themselves. (Though one might argue that they should read this stuff, in order to provide context for the job at hand).

In theory, having all of the requirements in one document makes everything easier to find, as well, and to see how all the pieces fit together. In practice, however, the document becomes difficult to manage as it grows over time, and these linkages fall apart.

 

The question that I always seem to ask myself when take a peek at a customer's requirements document template for the first time is, "why must us humans unnecessarily complicate our lives like this?"

One of the core reasons, I believe, is that managers still want to put their monogrammed gold pen's ink on something tangible, sign on the dotted line, and have everything recorded so that somebody (namely the BAs that report to them) can be held accountable in case something goes wrong... which will happen, because nobody understood, or questioned the contents of the document in the first place.

Luckily, from where I sit, I believe that the typical printed requirements document is nearing its death. And the good news is that this eventuality is closer than most people think. Yes, for some companies this dream will be further away than for others, but Blueprint has actually witnessed this happening at some of the more progressive companies that we've worked with (thus restoring my faith in humanity).

Tools for the Business Analyst, like ours, help to take requirements and break them down into managable deliverables, suitable for consumption by various stakeholders with different needs, while *still* maintaining cohesiveness.