Verifying Requirements Documentation

“Form follows function.”  This famous quote is sometimes attributed to the American sculptor Horatio Greenough, but in reality it was coined and made famous by Louis Sullivan, the American architect.  I thought of this architectural axiom when I read a BA Times article “Dazzle ‘em With Your Documentation Style!” (1).  In architecture terms, the article addressed the “form” of business requirements document (BRD).  Agreeing with the authors on enhancing the “form” of the BRD, I almost wrote a comment to that effect.  However, there was so much more I wanted to elaborate on in terms of the “function” of the BRD, I found myself motivated to write a “follow-up” article (reverse pun intended).  To be clear, “function” needs to be addressed prior to “form” in the BRD.  This article provides a checklist of best practices on verifying documented requirements – essentially the “function” of the BRD.

Verifying and Validating

Much has been said about verifying and validating the solution during testing at the end of a project.  An example of this is the V-model for testing (2).  Essentially in this model, the systems analyst verifies the solution to the specification followed by the business analyst/stakeholders validating the solution to the documented and approved requirements (assumes a waterfall approach).

• Verification answers the question, “Was the solution built right?”
• Validation answers the question, “Was the right solution built?”

However the same questions can be posed much earlier during the analysis phase of a project.

• Verification answers the question, “Were the requirements stated right?”
• Validation answers the question, “Were the right requirements stated?”

Documentation Best Practices for Stating Requirements

During the analysis phase, it is a best practice to validate the requirements with the stakeholders to ensure that the stakeholders agree (right requirements stated) with the stated requirements; typically this involves a signature to that effect by the business sponsor.  However, prior to validating the requirements, the business analyst needs to verify them (requirements stated right) with fellow business analysts.  Below is a checklist of questions for conducting this verification.  Each question is followed by the best practice rational.  Note that there is no order given for the questions; in practice the questions are considered simultaneously.

• Benefit Estimate – Does each process improvement or software requirement provide a business value?  Rational:  Benefits need to be cited and claimed in the business case.  Project benefits typically are based on process changes rather than the implementation of software.  Software is usually the vehicle that allows process changes.  Also see Requirements Traceability.
• Measurement (Leading and Lagging Metrics) – Are process improvement and/or software requirements (conditions) measured?  Rational:  Measurements are vital to support benefits (delta between AS-IS and TO-BE processes).  Process owners adjust processes based on leading metrics (in-stream indicators) to ensure that lagging metrics (process end result) meet expectations.  Note that process improvements may be modeled via flowcharts, UML models, or Business Process Modeling and Notation (BPMN).  Also see Feature Decomposition – Conditions.
  
• Transitional Process (Implementation Needs) – Are special considerations during process or software change implementation documented?  Rational:  Particularly with a legacy system, there are one-time tasks such as file conversions that must occur upon implementation of a replacement system.  In addition, process changes may be implemented in phases. (i.e., parallel running of the legacy and replacement system).
• Feature Decomposition – Are features broken-down (analyzed) into their simplest components by separating capabilities, conditions, and associated business rules?  Rational:  Features are high-level business requirements identified during the project vision and scope effort.  Breaking down features and separating them into their capabilities and conditions provides detail solution requirements along with their associated business rules. 
  • Capabilities — Each feature needs to be broken-down into one or more system capabilities (i.e., read, store, receive, calculate, transmit) and are of interest to solution developers since they reflect the inner system workings or regulatory, business, and user needs.  Simplify the capabilities by eliminating all conjunctions (and/or).  These capabilities are called functional requirements and can be written as user stories, declarative statements, or use cases.  Each capability needs to be stated positively (avoid the negative) and in the active voice using verbs such as:
    • must/shall (mandatory)
    • should/may (optional)
    • will (provided by an existing or future system)
  • Conditions — Each feature can consist of one or more system conditions and are of interest to the infrastructure developers since they reflect the characteristics of the overall system support.  These conditions are called nonfunctional requirements and are documented as declarative statements.  Note nonfunctional requirements are equally vital to document as are functional requirements.  Nonfunctional examples are:
    • Performance – what data needs to be on-line and at what access response time
    • Capacity – how many users / transactions need to be accommodated
    • Scalability – what is the growth forecast of the system (i.e., data, users, transactions)
    • Availability – when does the system need to be accessible
    • Security – who needs access (create, read, update, delete) to the data
    • Usability – what characteristics are needed to ensure a quality user experience
    • Data retention – what data needs to be retained and for what period
    • Backup and recovery – what data needs to be copied and at what frequency
    • Disaster Recovery – if services are interrupted for a prolonged period, what contingency plans are needed for the system
    • Training – what training is needed for users
    • Documentation – what documentation is needed for maintaining the system
  • Business Rules – Do solution requirements refer to one or more business rules as needed?  Is each rule independently defined and numbered?  Rational:  Business rules are obligations that constrain solution requirements and are of interest to the solution testers since they reflect the input criteria for testing.  To allow business rules to change independent of solution requirements, they need to be uniquely identified for reference purposes.  Rule examples are:
    • Definition – The meaning of a unique term, word or phrase (i.e., glossary or data dictionary)
    • Relationship – The link between two or more terms (i.e., entity relationship diagram)
    • Calculation – Formula used to derive information
    • State – Data qualification that is caused by an event (i.e., state diagram)
    • Range – Valid values for a defined term
    • Authorization – Permissions needed to access or perform action on data
    • Condition – Circumstance under which a business rule may apply (i.e., decision table, decision model)
    • Trigger – Causes an activity or a message if a certain condition becomes true
• Specifics – Are capabilities and conditions described in detail (i.e., who, what, where, when, and at what frequency/ volume)?  Rational:  In order to adequately test the solution, requirements need to provide the grade of quality needed.   Note requirements may be documented via user stories, declaratives or use cases.
• Requirement Dependency – Are requirement dependencies documented?  Rational:  Requirement interdependencies may be needed in order to realize business benefits.  Dependencies can also be outside the scope of the project (i.e., existing systems or other projects).
• Requirement Data – Are data needed by each requirement documented?  Are data defined and how they are created, read, updated, and deleted (CRUD)?  Rational:  Solution requirements encompass capabilities, conditions, and the data they use.  Glossaries, entity relationship diagrams and CRUD tables can be used for this purpose.
• Requirement Order – Are requirements ordered by business value (benefit, risk, priority, etc.)? Rational:  The development team uses this order as a baseline when determining the technical order for development.  Note that the development team may propose a different order for technical or resource reasons. 
• Requirement Traceability – Are requirements linked (forward and backward) to their original cited feature as defined in the vision and scope?  Rational:  Traceability is a risk migration strategy for maintaining scope.  If a requirement cannot be traced back to a feature, the scope has been expanded.  The objective of a project is to provide a solution within the project scope – no “gold plating.”  Whereas, the goal of customer service is to go beyond expectations – “wow” the customer.    
• Requirement Accountability – Does each requirement have an owner to ensure stakeholder support and adequate information for change management?  Rational:  Signature approval of requirements is needed to show commitment to the solution requirements and the benefits they represent.

Summary

This checklist provides questions to verify that the “function” of the documented requirements follow best practices.  Once “function” has been assured, “form” can be addressed as a second step of the verification.  Note that requirements verification needs be followed by a stakeholder validation and a system analysis feasibility review.

1. Verifying answers the question, “is the product or service being built correctly—per best practices.”
2. Validation involves stakeholders confirming “that the correct product or service is being built—per business needs.”
3. Feasibility is evaluating “that technology exists to implement the requirements—within project constraints.”

The above three steps needs to be accomplished prior to obtaining the project sponsor’s approval to proceed with development.  A similar verification with technical specifications and validation with requirements is done later on during solution testing.  As stated at the beginning of this article, this assumes that a BRD is developed using the waterfall approach.  Note the agile software development approach does not produce a BRD.  Verification and validation under the agile approach is conducted during testing at the end of each iteration (2). 

Post Script

At this point, I thought I would try to read some reader’s minds.  “Gee, the above checklist implies a lot of effort.”  Yes, it does.  Perhaps that is why it is called “work.”  Keep in mind that 40-60 percent of the errors in testing can be traced back to a poorly documented BRD (3).  We use best practices to reduce the risk of that happening.  Therefore, the amount of documentation effort needs to be based on risk.  To almost quote Shakespeare’s “Hamlet” – to document or not to document, that is a risk question.

Don’t forget to leave your comments below.

---

References

1. Spariosu, Nada and Rueffer, Patti (2011), “Dazzle ‘em With Your Documentation Style!” www.batimes.com
2. Monteleone, Mark (2011), “A Proposal for an Agile Development Testing V-Model,” www.modernanalyst.com
3. The Standish Group, The Chaos Chronicles, www.standishgroup.com

---

Mark Monteleone holds a B.S. in physics and an M.S. in computing science from Texas A&M University.  He is certified as a Project Management Professional (PMP®) by the Project Management Institute (PMI®), a Certified Business Analysis Professional (CBAP®) by the International Institute of Business Analysis (IIBA®), a Certified ScrumMaster (CSM) and Certified Scrum Product Owner (CSPO) by the Scrum Alliance, and certified in BPMN by BPMessentials.  He holds an Advanced Master’s Certificate in Project Management (GWCPM®) and a Business Analyst Certification (GWCBA®) from George Washington University School of Business.  Mark is the President of Monteleone Consulting, LLC.