Some recent posts across the blatherverse have highlighted some considerations that we as good business analysts must employ when developing and delivering our documentation and deliverables. These got me to thinking about my own very strong feelings in the past about what I should be doing as an analyst and how my audiences should be receiving my contributions. How arrogant is that? Who do I think I am acting like that?
The story with me has been that if I am hired to create documentation and other deliverables for either my development or business audiences, they have an obligation to read what I’ve done for the sake of the project and organization. While I do still believe that is true, I have also spent the better part of a year observing my working environment and reading the posts of respected peers and experts regarding documentation, methodologies, bridging the gaps of communication, etc. Why? Because something has been gnawing at me about this scenario. Why is it that people are not using or reading what I deliver?
Well, the fact is that there is not much value in the physical or perceived weight of my deliverable. Think about it. There is a line of diminishing return as the page turns in a massive BRD; I’m sure one that steeply drops into the abyss somewhere around page 319. So the more people are reading, the less they are absorbing and processing for use in their real work.
I’ve been failing. Period. My audiences are diverse and very busy; they simply don’t have the time they need to do things the way they should. Also, as the business world has become more competitive due to many factors, there is less money to produce documents that no one reads. So, I’ve found myself in the middle of a metamorphosis that I’m sure will have Scott Ambler ringing my doorbell any moment. Alas, this is not Agile requirements that I’m talking about (yet). It’s figuring out how I can adapt to serve my customers (Business and Technical) and deliver to them what they need in smaller volumes, without ambiguity yet with enhanced clarity.
See if you can respond with exceedingly good ways to deliver quality requirements WITHOUT mentioning any methodologies or best practices.
>>Let Go of Your Big Thick Requirements Document
Check out the Business Analyst Template Toolkit – the set of requirements templates host Laura Brandenburg has been using to replace 50+ page requirements specifications with a sequence of shorter, actionable documents, most of which are less than 3 pages long.
Click the link below to learn more:
https://www.bridging-the-gap.com/business-analyst-template-toolkit/
James already said what I was going to say, so I’m basically writing to agree with what he said. The need to document software for maintenance, use, and future modification exists, but should not justify spending time creating hundreds of pages of requirements documentation upfront.
The more detailed is your initial documentation, the bigger the risk that the document (or parts of it) will be obsolete by the time the systems goes into production. Requirements and priorities change, things that everybody thought would be easy to implement turn out to be unfeasible (requiring workarounds), etc.
The best time to write system documentation is post implementation, when it’s possible to document the system as it was actually designed and executed, not as planned and specified.
Back to Doug’s question, my documentation is typically composed of a high-level overview of requirements accompanied by diverse representations, such as use cases, annotated wireframes, illustrations of categories (e.g., “sales representative” and “engineer” are categories of a more general concept “employee”). The types of document produced vary from project to project, but the constant is that each document I produce is based on someone (either a stakeholder or someone from the project team – developer, tester, etc.) confirming that the document is useful to them.
If someone tells me they will use it, no matter how redundant it appears to be (e.g., a textual description of exactly the same thing I depicted in a class diagram, for a stakeholder unfamiliar with UML to be able to read), I’ll produce it.
Hello,
I found your question very interesting, since recently, in the context of my current project, I had a chance to give this subject some thought.
The value of proper requirements documentation upfront is that if it is done right, it is the product of good analysis of stakeholder needs. This in turn should result in better inputs into the design and development processes, i.e. proper context for the requirements, identification of the areas where designer or developer has relative freedom in what their solution looks like and where they are more constrained by the stakeholder requirements.
I agree that a massive requirements document, even if it is a product of rigorous and high-quality analysis is often essentially unusable. Different stakeholders have different “need-to-know” needs and putting everything into a single source of documentation has the tower of Babel effect.
My favored approach is for documentation to match phases of the analysis, where one goes from defining the big picture outlines of the solution to nailing down the detailed requirements. So instead of a large tome, there are several smaller documents targeted to provide the necessary information for each stakeholder type. Without reference to specific methods, let’s say there are 3 levels of analysis and therefore documentation.
First level is to document the broad characteristics of the solution – definition of the problem and its scope, approach to solution, major problem areas addressed, etc.
The second level of analysis is to identify the business processes impacted by the proposed solution and to define those impacts; to identify the major pieces of functionality and describe what they will do to meet the stakeholder needs. The level of detail on this analysis level depends on project particulars, but it should not go down the rabbit hole of individual requirement level of detail. It is the solution’s context and it should give readers the idea of what the entire thing looks like. Finally, the documentation for this level of analysis serves as a table of contents for the rest of the documentation. Thus, given the context, stakeholders can pick and choose business processes or features in which they have interest.
The third level of analysis is at the requirements level, centered around specific business processes or significant areas of functionality.
What I like about this arrangement is that it gives the stakeholders the ability to filter out the “noise”, i.e. specific things that have no direct impact on them, and focus on a smaller sub-set of documentation they must understand. I see some segments of the audience never getting to the 3rd level. I see some segments for whom 1st level is not much use. However, as a whole, you get reasonably close to a properly informed set of stakeholders. I have used this approach and I find the results promising.
Finally, regardless of the size of the requirements documentation, whether it is a large tome or many smaller documents, documentation is all about communication, and the same principles apply – simple unambiguous messages, communication channel free of extraneous noise, etc. A well-laid out and well-written document, no matter the size, has the most value. I have seen cases where a small document is incomprehensible, and a large document with loads of detail is very easy to understand.
Hope you find my contribution helpful.
My case is a different one,
My stakeholder never believed BRDs, RTM and Use Cases. As i joined my current company about few months ago, i used to fight for implementation of the processes including the mentioned ones, but i failed till recently. When i worked on a recent requirements and covered the importance of many aspects,it turned on my stakeholder and now, believe it, they have appreciated the concepts. Though, i was not to the topic of question, here i go.
When i started analyzing and documenting few requirements, my client saw where we were lacking, and were not prioritized. After reading on the BRDs and the useful stuffs, they really liked the concept of documentation, but as many of us believe, documentation consumes much time and no benefit of it in future trends, i propose, analyse on asking the right questions to get right answers and such an idea will brief some parts of the documentation in detail later on…
Gopal
James, Girish, Nageen:
Thanks so much for your comments and suggestions. As you know this is a fairly controversial topic when discussing the transition to a new state of documentation and there is much to consider.
Bridging-the-Gap’s readers will surely benefit from your intelligent contributions
Doug
Coming back to look at what I wrote I see I forgot to offer the option of a second split (checkpoint) in the project, and in the contract if there are external suppliers.
It could be at the point where you have produced an early prototype based on the outline requirements. That prototype can be used to derive the detailed requirements and build the final product. If there’s going to be just the one split then the second one would probably be better.
It’s important to remember the distinction between the two types of documentation. The types that is almost always essential tells us what the system does, and how it does it, so that the system is maintainable.
The sort of documentation that is of more dubious value is the hefty documentation that tries to tell us up front what is required.
Fred Brooks nailed the problem back in the 80s in his essay “No Silver Bullet”. http://www.virtualschool.edu/mon/SoftwareEngineering/BrooksNoSilverBullet.html
“The truth is, the client does not know what he wants. The client usually does not know what questions must be answered, and he has almost never thought of the problem in the detail necessary for specification. … in planning any software-design activity, it is necessary to allow for an extensive iteration between the client and the designer as part of the system definition. …… it is really impossible for a client, even working with a software engineer, to specify completely, precisely, and correctly the exact requirements of a modern software product before trying some versions of the product.”
So trying to pin the requirements down in precise detail up front is doomed to failure. Changes are inevitable, and are not simply a result of poor requirements specification, or irresponsible clients.
The implemented system doesn’t match the requirements documents. After all the effort that went into producing them there is never the will, the time or the budget to revise them to reflect what was delivered. Well, never in my experience anyway. So what you have is the worst of all worlds. Massive documentation with the associated expense of producing it, and a lack of useful documentation to help the poor souls maintaining and enhancing the system.
That’s not to say that documenting the requirements in advance is pointless. Far from it. But you do need to be conscious of what you can realistically do up front, and you have to take an iterative approach such as Cindy describes.
Unfortunately the desire to document the requirements in detail up front matched the needs of the accountants, lawyers and procurement when external suppliers are involved. None of them are comfortable embarking on a project with the requirements being uncovered iteratively. Software development therefore had to be contorted to make it manageable, rather than effective or efficient.
Iterative requirements definition seems a less comfortable approach, but the seductive charms of big up-front requirements definition are illusory. The reality is more painful, but you can always pretend you won’t have a problem till you start to get whacked over the head.
The first pass at requirements definition shouldn’t really be in any more depth than is required to size the work so you can plan and budget the full development with reasonable confidence. The detail should be deferred, because you’re going to get much of it wrong anyway.
I’m a fan of Tom Gilb’s argument that much of the high level requirements are a premature attempt to anticipate the design before the real business requirements are understood, even at a high level. Too often early requirements documents plunge into an attempt to describe how the problem will be solved, before there is a real understanding of what the problem truly is.
I agree with Cindy, In fact I just completed a BRD that’s was about 150 Pages long. I categorized it in to different sections like General requirements, specific cases like Notification, Interfaces, etc
Further I divided the business requirements like UI , Reports, etc in to a separate document This also helps in reducing the size of BRD and gives specific information to specific Developer (in Report Spec case a BI developer).
Further I also observed and got feedback from Clients that having a requirement number assigned to the requirement also helps in test cases traceability.
So the BRD would look like
General requirement
R1.0
R1.0.1
R1.0.2
R1.1
Hope this helps!
Girish
I agree with the fact that audience does loose interest in a lengthy BRD. That is the reason, why acceptance sessions are important. In an acceptance session the audience is expected to come prepared (i.e. after skimming through the document). The analyst gives a brief introduction and then answers the queries of the audience. This activity brings the audience closer to the BRD and so enhances their understanding. From my experience, I have felt that after the acceptance session audience tend to read the BRDs more thoroughly.
It is more like a classroom methodology where the teacher (the analyst in this case) introduces something in the classroom and the students (read audience) later read the topic.
The inference is, to make someone read your BRD, familiarize the audience with the key business rules and basic idea in a short session. This develops interest and wins you a reader
Our development team has different roles and different responsibilities. They include an Implementation Lead, a Technical Lead, and a group of developers. In addition we have testers and our product developers. The implementation Lead and the Technical Lead are responsible for the overall perspective and the developers are assigned very specific development tasks which relate to a specific subset of requirements.
So the Implementation Lead and the Technical Lead need to read the documentation and are part of the team that baselines the requirements.
In addition since we are doing iterative development, it is not required to have all the requirement done for the entire project on day one of design. We also write our requirements iteratively.
The key is grouping the requirements in a way that leads to the iterative development. To be honest I can’t really explain how I do this, but with years of experience it just comes naturally. We are developing web applications and I break the requirements down into components or specific functions.
It has worked pretty good for us.
One other comment, I am totally against creating documentation for documentation sake. I have found that is a good way of getting laid off from your job. I realize that documentation is important, but if the organization does not realize this and does not want to pay for this, I don’t push it. In my organization, excessive documentation is a big no-no.
Cindy:
I’ve been pondering the category issue as well and am wondering if you could expound a little more. The issue I’m seeing with that is the pot4ential tendency to have audience members become siloed, because they are only reading the specific parts that address their specific needs. A holistic view is very important and I would want to avoid messing with the ability to retain one.
Thanks Cindy
Doug
Aljaz:
I certainly agree that there must be some trail of what has been done in the past in order to understand capabilities of the future and your arguments are good for that. So the key is to not create the documents at all, but to hone in on the most valuable parts and then figure out if there are methods in automation or rethinking the minimal critical parts. Thanks very much for your input!
Doug
I have scaled back my documentation to only include specific requirements. I am letting other project documentation to stand on its own and not be repeated in the BRD. We work in a SharePoint where we have a dashboard that includes all project documentation for a specific project.
The other thing I take time doing is the organization of the requirements. By creating the right sub-categories it isn’t necessary for a stakeholder to read the entire document at one sitting. Instead, they can find and read the specific topic that they are working on.
We also have complete traceability and work in an iterative development methodology. So eventually each requirement is marked ready for test and as a result of this is read and is compared to the development effort.
Hope this helps.
Hi!
I feel your pain. However, in my opinion, documentation needs to be there, whether someone reads it or not. Eventually someone will need it, because he/she would like to know, how things work, otherwise the only solution is reading logic out of the code. I speak for solutions that are made for a long term when eventually no one knows how the system works. I have this at my current work (a bank) and it’s more than obvious that the knowledge of the current system is more or less in the heads of various people. Only few know the business process, most know small part of some process, while developers only vaguely know their application. This no-documentation approach might be managable for immobile workforce but there’s a very apparent and high operational risk should one person with some knowledge dissapear (switch jobs, retire, etc.).
How do I do it now? I still write documentation – for myself and for next generation BA’s who would the know where to continue from and then communicate what I wrote mostly orally, since – like you noticed – no one cares to read the stuff.
As for the financial part of the job: sure you can “save some bucks” on documentation, but you will cash out later when reverse-engineers come around to piece together the big puzzle.
I have a colleague in a company that’s doing agile method on development, but those were smaller projects/products. Now that they switched to a bigger project they found out that they’ll surely need documenting stuff – not in the agile way, but more of traditional kind of way. So there you go.
But then again, it’s nice to know I’m not the only one having these kind of problems. 🙂
Aljaz
Pingback: Tweets that mention I am letting go of the big thick requirements document. Are you? -- Topsy.com