Build Better Requirements Documentation: Why, Who, and How

A global corporation embarked on a software project to integrate its business systems around the world. The much-anticipated new product promised to improve information access, increase productivity, and reduce costs. Almost three years later when the software was deployed by headquarters, the regional locations refused to use it. The problems were not usability issues or missed bugs; the software lacked core functionality. It didn’t do what it was supposed to do. In some instances, it didn’t even do what the archaic, maligned system everyone had resigned to using did—what users needed it to do. Some teams within the company could no longer do their jobs. Instead of improving efficiency, the new software crippled the business.

This story is not unique or limited to enterprise software systems. New digital products, services, and IT projects ranging from internally built websites and mobile apps to purchased content and asset management systems are failures. Why? Among the various culprits, poorly defined requirements are often cited as a main reason. Incomplete, inaccurate, or missed (don’t forget non-existent) requirements increase the likelihood of a project failing to meet budget, deadlines, performance, and user expectations. Properly documenting requirements can help set your project up for success.

Why create requirements documents

Great products are built from great plans. They require research, a comprehensive strategy, and roadmap. Defined and documented requirements are a key part of the process for the development of a new or complex system. To ensure the product meets users’ needs, it needs to be understood, captured, and agreed upon. Knowing what is required and communicating it in a clear way is a critical part of any new project.

Requirements help communicate and define customer needs and problems. Through requirements gathering, stakeholders can establish a consensus on what is needed for customers’ problems to be solved. The process also can provide a basis for estimates, timelines, and, if used effectively, help prevent failures. The benefits include:

• Alignment: Consensus and agreement among stakeholders.
• Preparation: More accurate estimates for budgets and timelines.
• Direction: Information for design, development, QA, or vendor teams.
• Efficiency: A defined plan before starting design and code work.
• Productivity: Less rework and scope creep.

Where are you headed, how long will it take, and was it a success? Requirements are the compass for the project for everyone to consult before setting sail. Start off in the correct direction, and there is a better chance the project and its participants will end up in the right place.

The do’s and don’t’s of documenting requirements

The foundation for what will be implemented, requirements are statements that identify what the product does or shall do. A requirements document defines what is needed from the product. It states the product’s purpose and what it must achieve. It does not define how to deliver or build what is needed. While it puts the product in context to help explain why it is needed or what the problem is, the requirements do not outline the details of the solution.

Requirements define what is needed, not how to design it. Products like Confluence provide templates for documenting requirements. Source

Who does it and how

Despite evidence that clearly defined requirements at the beginning of a project can help prevent future problems, gathering and documenting these is a task that may be viewed with disdain or dread. It takes time and effort. It requires input from multiple parties (and actual end users). And, it takes someone with the skills to create a useful communication tool that captures and communicates what was learned for others to use it.

Gathering and writing good requirements should be a core competency for individuals involved in the creation of products whether its software, websites, apps, or digital tools. Whose role does it and how varies greatly. Larger corporations may have business analysts, systems analysts, and product managers dedicated to the task. Smaller company teams, start-ups, and creative or marketing agencies may have a UX strategist, project owner, or project manager filling the role. Titles don’t matter just don’t have the document owner/creator also be the product builder.

While almost any project can benefit from outlining requirements, how they are captured and documented doesn’t need to adhere to the same rulebook. Every team or organization should use a process that meets their development environment, needs, and project. The documentation type, details, and approach should match the scope of work, contributors, workflow, and resource constraints.

For example, capturing requirements in an agile environment, where a product owner and team quickly share user stories, may allow for a lean, less detailed document. While a massive product upgrade requiring input from multiple channels, across global locations, each with different business processes, technology systems, and stakeholders (and budgets) may benefit from a more detailed documentation and approval process.

Whether it’s a quick sprint or multi-year plan, what’s critical is involving key stakeholders early. Include the right people, constituents from business, technical, sales, customer groups–anyone who will build, launch, market, or use the product. Once the requirements have been gathered and recorded, key players should also help with prioritization.

Requirements included user stories, needs, research, and prioritization. Products like Inflectra can help teams organize requirements. Source

Requirements documentation types

Some requirements may only outline the high-level needs of stakeholders while others articulate capabilities, characteristics, or functions. An effective requirements document will communicate the problem to be solved, who needs it solved, and why. Understanding context will help teams make more informed decisions and build a better product. Approaches include:

Business requirements include high-level business goals. Why is the organization undertaking the project and what are the benefits to the company or customers? These may be embedded in other documents like project charters, vision, or scope documents. They may include project constraints (budgets, resources, schedule) and objectives but not specifics from which to build a product.

User requirements outline what users want to do. This documents the activities users will be able to perform with the product. Defining and detailing this is not the user’s job—never ask the user what to build. A seasoned BA or UX person can articulate what the customer or end-user actually wants and needs based on research.

Functional requirements state what the product must do. They communicate how it functions but do not dictate how to create it from a design/UI or the technical architecture. For software projects, these are often captured in use cases or user stories and outline what a user can get from the system.

There are many more types of functional and non-functional requirements and technical specifications. Some documentation may capture specifics about system, security, performance, integrations, reliability, and scalability. Determine the right approach based on the project. No matter the document type or its contents, make it easy to access, update, and control versions. Remember, the goal is the create a reference that contributes to the success of the project and not create bloated documentation no one uses.

Requirements Guidelines Checklist

A well-written requirements document is a beautiful thing. Requirements that are poorly documented can add confusion and complexity and undermine the execution. Use this checklist to create a document that is clear and helpful.

Does each requirement:

• Use clear, simple, and concise language.
• Use commonly understood terminology.
• Explicitly state the need.
• Have only one interpretation.
• Use direct, active statements.
• Express only one idea per statement.
• Articulate a unique point (is not redundant).
• Maintain consistently across the document.
• Have a means of verification. (testing)
• Specify a need and not design.

Does each requirement AVOID:

• Implementation details.
• Multiple directives or functions.
• Negative specification/outlining what it shouldn’t do.
• Subjective, vague, or undefined descriptors. (Fast, flexible, user-friendly.)
• Ambiguities such as “as appropriate” or “if needed.”
• Speculation. Users may want. Probably should. No wishy-washy statements!
• Asking for the impossible. (Asking for it to be 100% reliable is as realistic as saying it will satisfy all users.)

Don’t design the system. Design a great requirements document!