Blog post
Requirements… The why’s and who’s
There is one simple truth, and it goes like this: “In order to develop any meaningful piece of software by a multi-person team, you need to know what function that piece of software should perform and have that knowledge available to all team members at all times.”
The aforementioned knowledge in the written form is called the software requirements document.
Typically (and unfortunately), requirements documents don’t write themselves, so it’s clear that someone has to do that (very important) job.
That someone is called a requirements architect/engineer.
And to make matters a bit more complicated, that someone is also sometimes called a business analyst.
Also note that the role of a business analyst in IT context is somewhat flexible, and the finer details and responsibilities of them are quite dependant on the internal structure and processes of the given organization, and this text is no exception, as business analyst role described within might be somewhat (or very) different from the same named role in your company.
Although there are differences between the two, for the purposes of this text, they can be considered to be interchangeable, and we’ll use the term “requirements architect/engineer” to indicate both of them.
Requirements and the requirements engineer
Let’s consider a typical software development process and in particular, let’s observe that it contains some steps/phases which are ubiquitous across an entire spectrum of different versions/flavors of such a process. In other words, regardless of whether the said process is a waterfall process, an agile process, or just some custom iterative thing (or any combination of those), there are a few steps that are common to any of the mentioned “flavors” of it.
For example, any software development process would have to have some kind of step or steps where a part (or a whole) of the software under development would be coded/developed. So, for example, we could say that coding is one such ubiquitous software development step.
What we are stating here is that specifying the requirements is another such step.
Note that the format and the structure of the requirements vary significantly between the organizations and especially between different development processes (think of the differences between the story cards common to agile development vs 50+ pages of formal documentation common to waterfall development - and observe that both are, in fact, the documented requirements). However, one thing does not vary at all, and that is the fact that the requirements of some kind are absolutely indispensable artifacts of the software development process and therefore their production (engineering) is a ubiquitous software development step as well.
So earlier in the introduction and in the above paragraph, we figured out that the requirements are crucial and that someone has to create them.
That someone is called a requirements engineer/architect, and this text will try to explain which skills they need to possess in order to be able to produce high-quality requirements in the least amount of time, what are their main responsibilities and also cover one typical “documentation creating” scenario.
Essential requirement engineering skills and responsibilities
We’ll use the term “requirements engineer/architect” throughout this text, but the actual role we’re describing is a combination of traditional business analyst role, which Wikipedia defines as “A business analyst (BA) is a person who analyzes an organization or business domain (real or hypothetical) and documents its business, processes, or systems, assessing the business model or its integration with technology”, and a requirements engineer as defined in the “requirements engineering” process (https://en.wikipedia.org/wiki/Requirements_engineering).
There is much overlap between those two, and any requirements engineer is a business analyst to a significant degree and vice versa.
The main responsibilities of the requirements engineer/architect are the following:
1. Requirements Elicitation
2. Requirements documentation
3. Requirements review and validation
4. Maintenance of the requirements
Or, in short, the main responsibility of the requirements engineer is to produce the best possible quality requirements documentation within the given resource budget (ie. in a “quick pitch” scenario where the requirements engineer might be given only a day or two to create the requirements that would serve as a basis for an estimate for a quote, the detail level of the resulting requirements will be drastically different than those produced in the requirements capture phase of an ongoing well-budgeted project - determining the level of detail for a given resource frame is where Pareto principle shines and is essential).
What logically follows is that the main skills and the abilities that any requirements engineer should possess are:
1. An ability to learn new domains quickly (in order to elicit quality requirements from stakeholders/clients);
2. An advanced interview skills required to interview stakeholders and domain experts in a way that they can learn the nuts and bolts of a new domain quickly;
3. Expert analytical skills;
4. Deep understanding of the Pareto principle;
5. Expert knowledge of requirements documentation techniques and structure;
6. The ability to gauge which part of the requirements needs to be written in collaboration with domain experts;
7. Deep understanding of the review process and the ability to lead said review process and to elicit high-quality feedback;
8. The ability to competently verify the requirements in the following areas:
a. Functional completeness (ie. that the scope of all specified high-level use cases/stories/epics is fully covered with lower-level use cases - for example, given that there is a requirement which states that “administrators can manage the inventory of available products”, then there should be requirements dealing with how that inventory is managed by administrators - for example, requirements dealing with crud interfaces, any special inventory management features, etc. - the level of detail of those lower-level requirements is not really important, but making sure that there are no scope holes is),
b. Consistency within itself and with other systems (for example, if one part of the system is relying on soap interfaces and another that needs to communicate with it relies on JSON:API interfaces, or if a data entity is defined with one set of data properties in one part of the documentation, but another part of the system assumes the existence of another property or expects a different data type, etc.),
c. Alignment with the actual stakeholders expectations/needs (whether the high-level project goals defined by the stakeholders are really covered with requirements - ie. that the requirements describe a system that fulfills those goals with the least possible additional/unrelated scope),
d. “Implementability” (whether the requirements are actually implementable within the boundaries of currently used standards, available knowhow, and technology stack - for example, if the requirements define a high transaction volume distributed system and there is no knowhow in the company to develop such a system, or if company standard is Linux and the solution assumes easy integration with some Windows standard application such as Excel, etc.).
One thing we should mention here is that the requirements we’re talking about are primarily FUNCTIONAL requirements (use cases, user stories, functional acceptance criteria, etc.) and that most of the NON-FUNCTIONAL requirements, and especially those directly related to the specifics of the actual technical solution, would be defined later throughout the technical solution design phase, and are outside the scope of this document.
One common mistake is for the requirements engineer to try to write requirements for the domain they are unfamiliar (or simply insufficiently familiar) with or (this happens especially in those cases where the requirements engineer has a technical background) to try to produce technical requirements ahead of the solution design process. Both those mistakes are significant ones and should be avoided in any requirements creation scenario.
Documenting requirements - an illustrative scenario
So let’s now figure out one typical (albeit somewhat simplified) use-case for requirements capture/documentation. We’ll use case form as it’s well suited for describing the scenarios, but note that the depicted use case represents just one formal (and “waterfall-y”) way of creating a requirements document - the process below can easily be broken into iterations or the steps can be rearranged - as long as all the steps are completed, this presents no issues and will result in the requirements documentation of adequate quality.
Use case: requirements engineer produces requirements documentation
Trigger event
A requirements engineer is assigned to a project and instructed by the project manager (PM) to create the requirements for it.
Main success scenario
1. The PM instructs the requirements engineer on the scope and the purpose of the expected requirements (ie. rough estimate, solution design, etc.);
2. The requirements engineer informs the stakeholders/clients on the general details of the requirements capture process and then elicits the requirements from the stakeholders/clients (through one or more requirements capture sessions);
3. The requirements engineer determines that no domain specialist input is needed and documents the requirements using the standard requirements documentation form;
4. The requirements engineer confirms that the written requirements are:
1. Functionally complete,
2. Consistent within itself and with other related systems,
3. Aligned with actual stakeholders’ expectations/needs,
“Implementable”
4. The requirements engineer asks the stakeholders to review the documentation and they explicitly confirm that the written requirements fully match their expectations;
5. The requirements engineer asks the application architect to review the documentation and they explicitly confirm that the requirements are implementable without serious technical obstacles;
6. The requirements engineer presents the requirements to the estimation/development team and remains in the role of the internal consultant on the topic of the requirements and related project scope for the remainder of the project.
Extension 3a requirements engineer involves the domain specialist
3a1. The requirements engineer determines that they cannot competently write a part of the requirements due to insufficient knowledge of the domain and contact one or more domain specialists.
3a2. The requirements engineer presents the high-level requirements to the domain specialists and explains which parts require their direct input, and also explains the format and the expected content of that input.
3a3. The domain specialists create the requested content and deliver it to the requirements engineer.
3a4. The requirements engineer determines that the content is complete and accurate and rewrites it in the formal requirements form.
3a5. The requirements engineer asks involved domain specialists to review the formatted requirements containing their input and verify that the content wasn’t changed by the requirements engineer during the formatting process.
3a6. The domain specialist confirms that the formatted requirements are indeed in-line with their submitted input.
3a7. The main success scenario resumes from step 4.
Extension 4a requirements engineer iterates and updates documented requirements
4a1. The requirements engineer determines that the written requirements are either not complete, consistent, aligned, or are implementable and rewrites them until they are.
4a2. The main success scenario resumes from step 5 (stakeholders’/clients’ review).
Extension 5a Stakeholders/Clients discover missing scope elements
5a1. The stakeholders/Clients discover the missing or misrepresented scope elements and inform the requirements engineer of that fact.
5a2. The requirements engineer rewrites the requirements to include the stakeholders’/clients’ input.
5a3. The main success scenario resumes from step 5 (stakeholders’/clients’ review).
Extension 6a The application architects discover significant technical obstacles
6a1. The application architect discovers significant technical/implementation obstacles and informs the requirements engineer of that fact.
6a2. The application architect suggests changes to the requirements which would minimize and/or avoid technical obstacles.
6a3. The requirements engineer confirms that the proposed changes are accepted by the stakeholders and modifies the requirements accordingly.
6a4. The main success scenario resumes from step 6 (architect’s review).
Extension 6a3a Proposed changes are rejected by the clients/stakeholders
6a3a1. Clients/stakeholders reject proposed changes to the requirements.
6a3a2. The requirements engineer escalates the matter to the PM.
6a3a3. The main success scenario terminates.
Conclusion
To sum it all up - here are the main points to remember:
- You have to have requirements, their form may (and does) vary, but the fact that they are an indispensable part of any software development process does not.
- The process of capturing and writing requirements is owned and managed by the role called the requirements engineer/architect.
- Numerous techniques and formats (think use cases or user stories or gherkin examples, etc.) for capturing and writing software requirements exist. Those techniques are tried and tested over many years and in many scenarios, use them to your advantage.
Recommended materials
- “Writing effective use cases”, by Alistair Cockburn, a book that is, in my opinion, the definitive resource on the topic of writing use cases.
- “Specification by example”, by Gojko Adzic, a book that provides the context for the gherkin and all other example-driven requirements formats, as well as for effectively communicating requirements in general.
- Requirements writing “trilogy” blog posts (start here - all the other blog entries are linked from this one) - this series of texts should give you the detailed overview of which techniques and forms are applied when, why, how, and by whom - it should present you with a framework in which previously mentioned books will neatly “click”.
