Demystifying Digital Experience Platforms (DXP)
Jun 13, 2022 • 16 Minute Read • Elizabeth Spranzani, Chief Technology Officer
See All Our Insights
From Discovery to Execution: Why Requirements Documentation is Crucial to Your DXP Project
May 09, 2022 • 8 Minute Read
In this post, our Director of Technical Business Analysis, Mike Nairn, walks through investing in proper requirements documentation, a process overview, and how Verndale uses the functional documentation to inform the build phase of a DXP implementation.
Business Analysts (BAs) are highly collaborative, client-facing team members whose primary responsibility is to serve as the linchpin across strategy, creative, engineering, QA, and client teams. As product owners of the engagement on the Verndale side, it's a BA's role to gather, analyze, and maintain the business requirements of a project, a crucial component to its success. If the Engineering team doesn't know what they need to build or our client business teams don't have a clear idea of our recommendations, projects are subject to fail from a budget and timeline perspective. The BA supports the project by balancing a precise level of detail while providing the right amount of guidance to the team building the application.
What is functional documentation, and why is it important to our project process?
The purpose of functional documentation (or functional specifications) is to record all functionality related to the project. This documentation serves as the blueprint for the development team to build the application. It's also a detailed vision for what we intend to build to support our client's needs. We keep in mind the distinct needs of three groups so we can move quickly through the functional documentation and start the build:
- Engineering team: will be tasked with executing the build
- QA team: tests against the defined requirements
- Client team: signs off on the requirements
While investing in proper requirements definition is important, we also need to be mindful of the pressure applied to project timelines and not add any unnecessary bloat to our project process. Our playbook for defining requirements allows us to move quickly and accurately from initial definition to execution in the build phase.
To demonstrate this, let's use a hypothetical example to talk about how requirements are first defined to how they evolve throughout the 3 phases of a project; discovery, design, and build. In this example, let's say your current lead capture form on the website is leading to manual or duplicative processes internally.
To start, we kick off a project with a discovery phase, where we capture project requirements at a high level and build out the shared vision and roadmap. This is collaborative and done through a variety of meetings with our clients to discuss strategic goals, competitors, audiences, pain points, wants and needs, success measures, and more. In discovery, we want to capture the requirement at a high level to help inform the design phase, where the detailed requirements will begin. At this point, we don't want to dig too much into the details because we have an entire user experience to discover in a short amount of time.
In this discovery, we would capture the following details:
- Purpose of the form
- Expected audience
- What type of form we will build or use (custom, CMS provided, 3rd party)
- Where we need to route this data (to a sales person's inbox, captured as a lead in a CRM, or perhaps a CDP for identification purposes)
- If we expect any complex business logic
- Digital marketing goals and metrics related to the lead capture
Design phase: Types of Requirements & Documentation Captured
The design phase is not only for the creative teams to work their magic, but it's also where we complete the functional and technical design of the solution. This requires input from the business analysts, engineering, and the client project team. Taking the high-level details captured in the discovery phase, our experienced architects can begin to prototype the form (a grey-scale representation of the functionality in a live environment) before the design team illustrates what the front end will look like to the end user. This is where we begin to dig into the details to minimize surprises when we get into the build or start testing. Collaboration is crucial within our collective project team to come to a consensus on some important decisions before we can turn it over to the engineers to build. We are honing in on maximum clarity in vision and trying to minimize grey areas within the feature set.
Below are key areas we focus on and a list of questions. The answers to these questions are grouped into types of requirements included in the functional specification:
Functional/Feature Requirements
- Is this a single-step or multi-step form?
- What form fields do we need to include in the form at launch and are there any limitations to this based on the technology?
- What are the field types and their behaviors (single-line text, multi-line text, dropdown, etc.)?
- Which fields are required vs. optional, and what formatting requirements do we have for each field to ensure data integrity and accuracy?
- Do any of the form fields depend on each other?
- Do we need to pre-fill any values with user-specific data or default values?
Business Logic
- Should certain users see different options in the form?
- Should certain users not see the form at all?
- Based on the user's input, do we need to route the form to different locations?
- Are there any additional business processes we need to consider before or after form submission?
Technical Requirements
- What type of form are we using? Is it custom-built, a 3rd-party form, or a content author-managed form?
- How much control will the development team have over the look and feel of the form?
- On successful submission of the form, where do we send the data? And how does that happen? Do we use an API, a 3rd-party form, or another solution?
- How do we ensure interactions with 3rd-party systems do not cause any issues if those systems do not respond?
- Are there any additional systems involved besides the one we are submitting data to?
- Is there a limit on the number of submissions that can be made and what happens when we reach that threshold?
- Is there PII we are capturing and any compliance requirements we need to adhere to?
Administrative/Content Author Requirements
- Where can the form be managed in the experience? Anywhere, or restricted to certain areas?
- How is the form managed? Is this a 3rd-party form we are dependent on for all functionality or CMS-provided where the content author can add fields as they wish? Or is it custom and we need a developer to make changes?
- If fields can be added to the form, what is the process for making sure this is supported by back-office systems?
- How are success and error messages managed?
- How can content authors manage the labels of the fields?
Experience Design Requirements
- What should the tablet and mobile experience be?
- What should happen upon successful submission?
- What does a client-side error look like to the user? What does a server-side error look like to the user?
- Is there an interactive state on the focus of the fields? Do we need placeholder text in the fields?
- Is there a loading state to indicate to the user that the submission is in progress?
- Are there any other interactive or hover states we need to consider?
- What considerations for accessibility need to be applied?
If there is complex business logic involved with this form, a data flow or process diagram may be produced to help engineers and business users with context to understand the whole picture. If we need to send data via an API, we will want to include the API documentation as a reference for the engineers. The end user may see only a form to submit a request for a quote, but there is a lot of analytical thinking, use cases to consider, and decisions to be made behind what we'll ultimately build. This is how we come to a consensus across design, technology, digital marketing, and business needs.
Review and Approval Process
The review and approval of the documentation is a key component of the 3-part phase we have in place in our projects. Verndale teams and our client teams review and sign off on documentation. These reviews serve different but equally important purposes to minimize unexpected scenarios and move faster with confidence for our final phase: the build.
For Verndale reviews, we're vetting for technical feasibility. This is how we build the backlog with precise requirements, have informed team members, and estimate our build phase. Here, the functional specifications are being defined and passed through various teams to check for accuracy, alignment, viability, reusability, and context to inform the overall architecture.
The goal of our client review is to sign off on alignment for the final delivery and to discuss any dependencies in the partnership. Any feedback or changes are made as revisions to meet your needs and tweak the build estimates.
Build Phase: Execution and Maintenance
Once our requirements are approved, we have our build backlog and the corresponding estimates. We're ready to prioritize the work and create our build timeline with a high level of accuracy.
Here's where it all comes together. The engineering team is able to pick up tasks linked to our documentation and understand exactly what they need to do to complete their work. Our QA team is able to write their acceptance tests based on the requirements that they will use for functional testing. The BA and client teams are able to look back at the documentation whenever there's a requirements question and see the history of how we arrived at the approved requirements or why certain decisions were made. Comment history in-line within the documentation make it clear who gave approvals and what thought process was involved.
The BA is responsible for keeping the documentation up-to-date and accurate throughout the build phase, an important and often overlooked part of the requirements definition.
We need to embrace the fact that we'll never be able to write perfect requirements for a project, just like there will never be a software development project without bugs. When there is a change in requirements, or an assumption is invalidated, the BA will update the documentation and ensure a transparent conversation around scope happens if necessary. There may be re-estimation or discussions with our client teams required. However, with the level of detail we capture in the design phase, we expect only tweaks during the build and not major changes.
At the end of the successful build phase, we're able to hand off the up-to-date requirements to our clients as an important asset in their continued evolution. Most importantly, this blueprint for the application can be used for continued project phases and future enhancements. Our client teams can use it to inform a common understanding of what the application does, and easily onboard new team members.
If you're considering a project where this would add value, we would love to hear from you. Contact us and and we'll offer insight into how we can help.