This article is a requirements document template for an IT reporting project, based on my development experience as an SSRS, Crystal Reports, and Access developer and staff manager over the years.
For a Requirements Document Template for an ETL Project see my article here.
After enough trial and error from the best and worst clients, business analysts, executive sponsors, and my own shining and less-than-shining moments I have seen many developers confronted with poor requirements turn into ... the DEV Nazi!!
In scope for this article
Out of scope for this article
(But maybe if you vote Yes and comment nicely at the bottom of this article I'll write another article on it.)
So here we go..
A 'who changed what when' chronology of all changes, either using Word change tracking or lines like 'Bob's changes in yellow highlight'. Keeps everyone honest when there are lots of changes.
Also known as project objective, business goals, business problem statement, and various other terms.
A simple 'Here's why we're doing this' paragraph. The target audience being those that are likely to only read this paragraph, but this also gives the developer some design decision guidance.
In Scope / Out of Scope
Everybody LOVES this section! Okay, developers LOVE this section. In Scope is a summary of what's in the requirements. Out of Scope is usually a Top 10 list of things that are close but not in, and answers the often asked question 'Are we also getting this too?' This is a developer’s best line of defense against scope creep by false or unstated expectations.
And yes, just because person x told person y a month ago that it’s in requirements, or this email two months ago said it’s in, or was mentioned on the golf course last year during preliminary negotiations means that it’s in. I've also known more than a couple of clients that will negotiate effort, cost, and time, and then scope creep the hell out of a project in order to make themselves look better. Been there, dealt with that.
A statement on when this can be completed, such as 'When division X is in the data warehouse', 'When project ABC is completed', 'Beginning in FY 2013', 'Yesterday', etc. Helps project managers plan this project within a project management system that deals with all projects, all resources, and available time.
User supplied values that will change the population. For each parameter
For each section
For each column
Fun fact: Providing a PowerPoint presentation from some VP and saying 'these numbers are just to illustrate the concept' is not a good requirement for a calculated column. Trust me on this one.
Does any part of the report have to match other parts of the same report? (i.e. Sum of Dollar Amount matches ‘Grand Total’ text box)
Are requirements easily understood?
Any confusion in requirements is going to be defined differenty by different people, resulting in time and effort, and goodwill if that confusion is between you and the client.
A big honkin' list of other quantifiable things you may need to directly address
Availability, Capacity, Data Currency, Data Retention, Degradation, Deployability, Exception handling, Extensibility (flexibility), Internationalization, Interoperability, Audit logs, Maintainability, Portability, Privacy, Recoverability, Reliability, Response time, Scalability, Security, Upgradeability, Usability.
NOT to be confused with these MBA Buzzword Bingo words, which may sound real impressive but have no quantifiable characteristics whatsoever:
World-class, best of class, best of breed, industry leading, empowerment, collaboration, repurpose, frictionless, client-focused, ecosystem, excellence, synergize, geo-targeted, diverse, environment, core competency...
10 If requirements documents were easy, they'd offshore both the requirements and development for a third of what you cost, so don't get bent out of shape when things are complicated. It's job security.
9 Never underestimate the awesome power of a :: blank stare :: to get people to provide you with better requirements
8 Sometimes 'draw me a sketch' is an excellent place to start requirements elicitation.
7 Never assume customers know exactly what they want. Sometimes you have to guide them to the answer.
“If I had asked people what they wanted, they would have said faster horses.” - Henry Ford
6 Scope Creep - Changes in requirements after the initial ones are approved, but there cannot be an expectation that they will be immediately accepted. They must be managed with budget, schedule, and resources.
5 Make sure the right stakeholders are defined, included in requirements elicitation, and accountable. Especially if there are multiple groups that have different opinions on what the requirements should be.
4 You are not an order taker! (see 'Faster Horses' above). This means you have to own your expertise and discover your customers needs together
3 Being a Business Analyst is its own career track, with its own training and certification. The IIBA has plenty of resources.
2 Requirements documents should be signed by all customers. In blood would be preferable, but in modern times ink is an acceptable alternative. ... and the number one tip for writing requirements docs...
1 Any requirement that is missed, and caught in later stages of development, will cost WAY more money to fix, so make sure you get it all!!
Thank you for reading my article, please leave valuable feedback. If you liked this article and would like to see more, please click the Good Article button near the bottom of this article.
I look forward to hearing from you. - Jim ( LinkedIn )
The material in this article was presented at SQL Saturday #682, St. Paul Minnesota, 2017.
Have a question about something in this article? You can receive help directly from the article author. Sign up for a free trial to get started.