Top 15 Requirements Documentation Bad Habits
How confident do you feel about the wholesomeness of the food served at a restaurant with torn carpeting, dirty silverware, and sticky menus?
Why should your documents be any different? Your documentation is the container for the findings of your effort. The container itself creates the first perceived value about you and your capabilities. This becomes more of an issue if the document is presented to an external department or entity.
Most projects are conducted on a rushed timeline with a focus more on the mechanics of requirements elicitation and less so on documentation practices. This is where you may get derailed and become susceptible to bad habits that make you vulnerable to documentation shortcuts and errors. Many of these bad habits can be enabled by an organization’s need to “Just get it done,” and not necessarily be a reflection of a BA’s capability. Nevertheless, these need to be held in check by a watchful eye. Here are the top 15 Requirements Documentation bad habits:
1. Releasing an Approved Document with Markups, Highlights, and Notes
Keeping your strikethroughs as you revise an approved document is good practice so the revisions can be tracked. MS Word Track Changes is sometimes used for this also, but soon becomes a mess. There is no excuse for this during the initial release. The neighbors don’t need to see your dirty laundry. In this case, it is the muumuu dress of the documentation world that screams “I don’t care what I look like.”
2. Writing Requirements in the Scope Section
The scope section defines the boundaries of the effort. Tell just enough to describe the high level view. Save the dive into the weeds for the requirements section.
3. Accepting Conditional Approvals from Stakeholders
You just created a fuzzy spot for scope creep. The stakeholder should have already been participating in the creation of requirements. They could have stated a dependency or asked the project manager to log a risk.
4. Business and Functional Requirements Confused
Ideally the WHAT is captured by business requirements defined by the business, and the HOW is captured as functional requirements by the IT department. The separate intentions of the two are often misunderstood. It’s not uncommon to find a firm that wants functional requirements mixed in with the business requirements. This is typically due to the lack of definition of roles and responsibilities between the business and IT.
5. The Out of Scope Statement “Whatever is Not Stated as In Scope”
This is the lazy person’s way out. You may need to learn more about the subject in order to appreciate the boundaries. Is there something that a person not familiar with the project may confuse as being part of the project? This is where you eliminate that confusion.
6. Missed Assumptions
Assumptions are often skipped because we think they are obvious. Assumptions help paint the context and provide a layer of nuance to the scope. Remember, the documentation is also intended for people who didn’t attend the elicitation sessions.
7. Background Statements with Weak or Missing Content
Analysts are quite right brained, so requirements come quicker to mind. Background statements are more left brained and seem to use a muscle that rarely gets exercised. It’s surprising to see how many people struggle with this. Don’t assume that all readers know the basics of the backstory.
8. Misspellings
Yes, we have spell check, but too many misspelled words still slip through. Do you ignore that squiggly line or procrastinate when dealing with it? Sometimes the software behaves badly and doesn’t activate the spell check feature. Software gremlins may spell check the body and skip the contents of a table. Even the spell check needs to be checked.
9. No Sequence or Grouping of the Requirements
Humans tell stories chronologically. The requirement document has much to tell also. Some of it can be confusing. Chronology is important since one requirement can actually help provide some context for the next. Some requirements are best treated as a family and grouped in a subheading.
The relationship of these requirements becomes more apparent.
10. Not Making Use of the Appendix
The appendix is a good solution to cluttered formatting and is a great place for useful information. There is often information that is too large to be placed in the requirements section without blowing it up. Sometimes there is information that would not be considered as a requirement, but still is good to know. This is where you park it.
11. BRDs That Don’t Get a Second Set of Eyes
A doctor is his own worst surgeon. Even a BA as a practitioner of best practices can only catch so many of their own errors. A peer review process would be great for this, but even a look-over by a trusted coworker can prevent huge errors and embarrassments.
12. Missing or Meaningless Diagrams
A picture is worth a thousand words. Most humans think visually and understand more quickly when there is some type of visual demonstration. A flowchart of processes that lay out a sequence conveys not only what a current state is, but also can be used to illuminate pain points and deficiencies. A future state flow can build a mental framework that clarifies the relationship of requirements. Copy diagrams with care. A fancy diagram copied from the executive program kickoff meeting may be colorful and pretty, but can easily provide no sustenance in communicating the elements of the project you are tasked to define.
13. Telling a Story Instead of Requirements
Separate requirements speak for themselves and are less likely to confuse the intention of the next requirement. BRDs usually support the Waterfall development process. This relies on individual requirements that can be validated by a single test. If you are using the requirements document as a vehicle to build an Agile backlog, then capturing your requirements in a story format might work for your situation.
14. Pagination Imagination
The red flag speaks for itself when your last page is numbered “11 of 13.”
15. Leaving Sections Blank
It looks like you forgot to complete your job, or worse yet, didn’t give a damn. Entering a “N/A” won’t break a sweat on your knuckles. You can show more diligence with a “None Identified.”