What should the goal of writing requirements be? Which audience are you writing for? What format and style of writing works best? Who should review the requirements? How technical should they be? What tools are best to use when writing your requirements? These are all questions you should be considering before diving into requirement writing. In this second Project Insights article, we will examine each of these challenges and discuss best practices suited to a variety of different project scenarios.
In my first article, I covered the important aspects of the kickoff phase of a project and what steps can be taken to set your team up for success. Some of the kickoff phase steps such as defining goals, setting priorities, determining a schedule, and other important steps will tie into requirement definition as well.
Before requirements are written, it’s important to be aware of the project’s priorities and dependencies. Let’s consider a simple example. Your team is tasked with making updates to an existing sports app. Your list of features includes analytics additions, settings updates, rewriting two views, live game updates, and ad updates. The client has defined what is most important to their business as the product owner. Your team should also assess the feature set and make recommendations based on priorities.
A white-boarding session is perfect for this exercise, especially when you have an extensive list to analyze. Factoring in the project’s known dependencies, you may note that the addition of ads to a view will actually need to happen after you rewrite that view. Next, you may discuss that changes to a live game state may require simulation testing to verify that the changes are working as intended. A significant change to a live game state might also be the most risky change to the app, and you’ll raise the priority of that feature over others. Settings updates, being easy to update but the least important to users, keeps that feature low on the client list and low on the list of priorities. It is important to continue iterating through this process until you come up with your final order of features. From there, your requirements should be written in the same order and you should strive to stay ahead of any development sprints being planned out.
A requirements document serves multiple purposes. The goal is to document as much detail as possible from a business and functional perspective; however, depending on the item you are documenting, you may have limited knowledge and it may require some development discovery to complete full requirements. Requirements should be reviewed by multiple parties and be approved by stakeholders.
At POSSIBLE Mobile, we typically document full requirements for our clients based on whatever level of detail is initially provided from them. Some projects have dedicated business analysts for writing requirements, while others are written by a combination of the project manager and a technical lead. We also know that it’s incredibly beneficial to have our QA Engineer review the requirements as they often come up with use cases that may have been missed. After a rigorous internal review, we then provide the requirements to the client for product owner review and approval. Another purpose for requirements is to set expectations. The initial approval is the starting point. If there are changes or additions, then they are handled through a change management process as defined by the project.
Requirements should be a living document and the team should always have access to the most recent version. This becomes critical as it comes time to verify requirements through QA. Requirements should also be logical and easy to consume. As an example, if we are documenting a new app, there should be multiple pages that break down components, such as global components versus particular views, and within each page we break out each item based on the development process and steps. In order for requirements to be a living document, it’s critical to have the proper collaboration tools. There’s nothing worse than trying to handle multiple versions of a Word or Excel document.
Wiki tools like Atlassian’s Confluence offer the perfect solution for documentation because of the ease of use and capabilities it provides. After analyzing many projects across our business and how the requirements were constructed, we developed our own requirements template within Confluence (which can be created in Global templates with Admin access) to use for our projects. The final version focuses on simplicity. Some of the key elements include:
- Requirements Table
- Design style guides and assets
- Links to JIRA tickets
- Approval checkboxes
The overview provides the high-level summary of assumptions, dependencies, and what’s detailed in the requirement page. The requirements table contains each item, it’s related design and detailed requirements. We also include links to JIRA, Atlassian’s project workflow tool, for easy access to JIRA tickets for tracking design, development, and QA work. When requirements are ready for review, our clients are able to access the specific requirement page on Confluence and comment with any changes or additions. This provides a paper trail of discussions and decisions. Lastly, Confluence has a new capability that allows multiple users to collaborate on the same document and it also provides page history so users can compare changes over time.
Styles and Format
The best style and format for writing requirements often depends on the particular feature and the team implementing the work. Let’s review a few examples.
Example 1: User Interface
In the case of documenting user interface (UI) requirements, it’s helpful to provide a visual of the entire UI, but then break down the view by individual items. From there it’s helpful to document with a top-down, left-to-right approach. We recommend using a table that lists the item in the view needing to be implemented, the design of that element (whether annotated or individual images from the UI), and the detailed requirements. The detailed requirements focus on business and functional concerns. We also define all use cases that need to be handled, which often tie to test cases that our QA engineers use to test the app.
Example 2: Data & Networking
When writing Data & Networking requirements, we start by creating a Data Flow Diagram (sometimes called a “DFD”). This is similar to how we would approach a brand new application that covers the user experience flow, but in this case we may start with the API (Application Programming Interface), which works as the intermediary between the app UI and data flowing into the app. Our diagram will include the flow of how to perform the desired network requests as well as how we are going to parse and store the data before presenting it on the UI. In more detailed requirements for specific views in the app, we cover the specific feeds we are requesting. If the data has numerous states, we also document each of the states and the expected data that should be returned from the data feeds. Another case covers how we handle failures and errors. This type of requirement obviously needs to focus on the technical details.
Example 3: Ad Requirements
A lot of mobile applications generate revenue by including advertisements. The best ad implementations address the goals of the advertiser with readily visible content, but avoid disrupting the core user experience. When writing requirements for ads, the overview should describe which ad provider(s) the mobile application needs to integrate with and where the ads should appear. The requirements should include the ad provider’s documentation and links to the SDKs (Software Development Kits) to be used during the implementation. Designs for the ads provide the visual guideline, but detailed requirements should include the various ad sizes that can be served, placement options and rules, the type of ad, and the page name to use. Ad providers can also have specific rules around how to render the ad as well as specifications for refresh intervals.
At POSSIBLE Mobile, we like to make sure that we are at least covering the business and functional requirements when documenting. We try to keep documentation in Confluence and then provide links to JIRA, which tracks the flow of work for a given sprint. This doesn’t mean that we never add additional details to JIRA tickets, but if we do, they are typically technical decisions made about preferring one approach over another based on platform-specific best practices. When needed, we even do break-outs after sprint planning with the team so that developers can influence decisions prior to implementing any code. Design-specific meetings are also scheduled and can vary based on the design task at hand. Whenever designs are approved, we make sure they end up on in our requirement pages, ensuring the team is in sync on final design decisions.
For those of you that are advocates of agile methodologies, you might ask yourself why I didn’t recommend user stories in any of my examples. If your team is used to working with user stories and that’s what works best for your team, then continue down that path. User stories provide the benefit of making sure the team is considering all potential end-user scenarios and answering the “whats” and the “whys.” As an example, you would work through requirements by stating, “As a mobile app user, I want (what?), so that (why?),” and then you would follow that up with acceptance criteria, thus covering all use cases. I personally find user stories to contain repetitive information, whereas good requirement writing should include the answers addressed with a user story.
No matter what style of writing you take, there are numerous options for structuring requirements and determining the best approach for documentation. As seen in the above examples, it can vary, but taking the time to think through the approach of the requirements will always result in a better finished product. In addition, having multiple sets of eyes on the content will help to flesh out different use cases and alleviate headaches down the road. Setting priorities will allow you to stay ahead of the upcoming sprint, but not too far ahead in case the team needs to pivot based on scope changes. The documentation will also serve as a blueprint for your QA team to write test cases for new features, which can be added to a suite of regression tests to be used for final testing of an application. It can also be beneficial to reference requirements when going through a demo of features completed in a sprint. We’ll cover more on that topic in the next article in this series where I’ll cover the benefits of effective sprint planning and sprint demos. Stay tuned for more.