Keeping track of requirements with lightweight tools

Swat.engineering wants to help its customers deliver the right value. So we often start with a requirement analysis phase. This yields a requirement analysis report: How can we use the least amount of tools and overhead to focus on the essentials? We’ll show you how we use Google spreadsheets, Rascal, and HTML to generate interactive/traceable requirements. These requirements can not only guide a single software project but they can also be used to formulate a full project roadmap, see From Requirements to Roadmap (to be published).

Our approach

We produce a requirement analysis report by:

1. Immersing ourselves in the project domain;
2. Eliciting requirements from all stakeholders;
3. Structuring requirements in traceable documents.

Immersing ourselves in the project domain

(And yes, this is inspired by techniques from Domain Driven Design)

We need to create our own mental image of stakeholders’ needs and the domain they operate in. When we start, we are often largely ignorant of the specifics of the domain and organization. However, near the end of the requirements project, we are often viewed as experts. We achieve this position by:

• Studying internal documents;
• Following training, or at least studying training material, wherever possible;
• Creating a predefined set of questions we want to ask a diverse group of people, at least all the different stakeholders.

Armed with this initial (and probably partially incorrect) understanding, we seek interaction with our counterparts.

Eliciting requirements

Now we enter an iterative process of gathering, aggregating, and organizing information. We iterate between eliciting and structuring requirements (see the next section) by using the following steps:

1. Schedule interviews with all stakeholders.
2. For every interview, ask the predefined questions but leave ample time to get the interviewee’s input on anything related to the project.
3. Collect requirements in a freeform format document.
4. Bring structure to the requirements (see below).
5. Discuss the structured requirements with the stakeholders, and use the feedback to fine-tune these.

We often notice that a well-structured requirements document helps stakeholders to understand each other’s concerns better.

“We already have user stories, so why do we need requirements analysis?” We think user stories have a place, but for larger projects we have discovered that some upfront requirements engineering (and architecture design) is needed.

Structuring requirements

We structure the requirements by splitting every requirement into four categories (based on BABOK):

• Business requirements: business-level desires such as faster time to market or lower maintenance costs.
• Stakeholder requirements: a stakeholder’s implementation of a business requirement. For example, we want to be able to implement a new mortgage product within 2 weeks.
• Solution requirements: a desired solution strategy for specific stakeholder requirement(s). For example, develop a mortgage definition DSL that generates COBOL code that integrates with existing infrastructure.
• Implementation requirements: constraints for the development process that are directly related to business requirements instead of stakeholder requirements. For example, plan for incremental integration or have high test coverage for all new features.

We then use a simple spreadsheet to describe all these requirements and link the lower levels to higher levels using data validation formulas. The following embedded spreadsheet shows an example of a requirements specification:

📖 Load embedded spreadsheet (accepting Google Docs cookies) 🔗 Open spreadsheet in Google Docs

Based on this structure, we use Rascal to generate interactive HTML pages. These can be published on the intranet or be turned into PDF pages for distribution. Changing these documents is easy, as it only entails updating the original spreadsheets. The following embedded document shows an example of such a generated HTML page.

Key takeaways

1. When eliciting requirements, keep track of all available information in a single spreadsheet.
2. Linking to other requirements or projects can be automated, which helps maintain consistency and evolution.
3. Stakeholders receive documentation that has a clean structure, is browsable, and can be quickly updated with new insights.
4. Only a few tools are needed: spreadsheets, an HTML generator (in our case, implemented in Rascal), and a browser.
5. These requirements can form the basis for formulating a roadmap (see From Requirements to Roadmap (to be published))

Get in touch

We’re happy to discuss how our approach to requirements engineering can help you gain insight into the goals, needs, and constraints of the software in your organization.