24 Oct Quick-Turn Requirements
The word “requirements” is often associated with long, unproductive meetings with two people haggling over minutiae while a dozen or more others sit bored in a conference room. This negative image causes companies to resent requirement-writing, and some skip it entirely to spare themselves the burden. However, as described in our blog entry, “The Importance of Clear Requirements”, the consequences of doing so are worse than going through the pain of requirements development. But what if requirements development didn’t have to be painful? What if it could be done quickly and efficiently? This blog explores ways to expedite and improve the efficiency of the requirements-elicitation process.
Requirement Development Process
Requirements development is a process, and while not complicated, it is easier when one understands the whole process and can identify one’s position therein. The process consists of a series of phases, described in the following sub-sections:
During the Elicitation phase, systems engineers work with the customer to think through the details of the product. What will it do? How will users interact with it? What interfaces to other equipment does it have? How is it powered? These are just a few of the questions asked during this phase. The output of this phase is a list of notes about the requirements, but it’s possible that there is not a single “shall” in this list. This could be likened to an explorer picking his way through the forest; all that’s left behind him is a trail of stepped-on grass. The path he chooses may not be the ideal one, but it gets him slowly to where he’s going, and others following closely behind can still pick up his trail.
In the Draft phase, the requirements are written down in a “quick-and-dirty” fashion to begin to shape the requirements into something that can move forward. The requirements acquire their familiar “shall” format, but they may not yet be very thorough or consistently interpreted. There may be missing requirements, and there may be TBDs still present. Continuing the explorer analogy, the explorer has grabbed a machete and has hacked out his trail. The trail is still rough, impermanent, and weaves a bit, but it’s good enough that others can follow it.
The Refinement phase is where the requirements are honed to turn them into “good requirements,” that is, requirements that are clear, complete, consistent, atomic, abstract, precise, feasible and legal, necessary, testable, and unambiguous, presented in a manner that is well-structured and free of duplication and redundancy. Additional requirements are added where needed to flesh out the more complicated aspects of the product, duplicated requirements are removed, and requirements in separate parts of the specification that describe a feature are grouped together or cross-referenced. Subject-matter experts are consulted to make sure that the requirements cover everything that needs to be covered and don’t dictate implementation. Our explorer has brought in a clearing crew so that the surveyors can follow. It’s hard work, but the effort spent will make the task easier for everybody who comes afterwards.
The Review phase is when the requirements are disseminated for review from those not actively involved in their development to make sure that the requirements are understandable by everybody on the team, and the requirements are updated with the feedback from the reviewers. In our analogy, the surveyors arrive and set the final path for the road. It’s time-consuming and sometimes uncomfortable, but it’s absolutely necessary if the road is going to be strong and durable once built.
The Approval phase is reached when all of the review feedback is implemented, and everybody is satisfied that the requirements accurately describe the product in a way that is consistently interpreted by everybody. In our analogy, the survey is complete, and the road is built. Developers now have a paved highway they can follow when doing their development, rather than each one having to pick his or her way through the forest, potentially going off in an unexpected direction or getting lost.
The Revision phase occurs later in the project, when the requirements are updated to reflect new understanding of how the product should work discovered during development. This phase contains some or all of the other phases: new requirements may be elicited and drafted, existing requirements may be refined differently, and all requirements undergo review and approval. In our analogy, the need has come to widen the road, and so the explorer sets out with his machete, this time with the existing road to guide him, and he is followed by the clearing crew, surveyors, and building crew to finish the job.
We’ll reference these phases as we discuss how to maximize requirement development efficiency.
Requirement Development Strategies
The following sections present ways to improve requirement development speed and efficiency and examples of how using these strategies has helped Realtime to help its customers develop their requirements quickly.
Just Do It
First and foremost, don’t make the mistake of just skipping the requirements. Here at Realtime, we have a saying that “One way or another, the systems engineering will be done.” This can occur either upfront as an organized, planned effort, or haphazardly and inefficiently as developers iteratively produce output that doesn’t match customer expectations. Make the decision to knuckle down and “just do it”; the effort spent will pay dividends. Realtime can help.
Ivory Towers and Dull Meetings
Requirements development requires input from many different groups. Effective requirements cannot be generated from atop ivory towers or from within siloed departments. On the other hand, it is inefficient and frankly a waste of people’s time to invite everybody to a huge meeting where most people have little or no input to add.
Systems engineering is at its nature a social discipline: it requires talking to all of the affected parties: customers, project management, developers and/or subject-matter experts (SMEs) in each of the affected disciplines (including compliance and quality), and test. The ideal case is to facilitate a series of smaller working sessions with just the people who are directly affected, and then push out the requirements to the larger group for individual review. Here are some specific suggestions, based on the requirements development phase.
During Elicitation, a meeting is the most effective way to rapid-fire questions and answers back and forth. It is worthwhile to have one representative from each group present to bring the different groups’ perspectives when doing the initial hashing-out. One or more people should take notes to make sure that everything is captured, but attempting to formalize into requirements, even draft requirements, should be done as an individual effort, sparing everybody in the room the boredom of watching somebody type “shall” ad nauseam.
In the Draft phase, one or more systems engineers can transcribe the notes from the meeting into a set of preliminary requirements. At this phase, there may still be a lot of TBDs that need to be addressed, and the preliminary set of requirements may not consider nuances in the implementation that may require additional or different requirements. This is okay; the goal of this phase is to blaze a trail in roughly the right direction; the requirements are almost guaranteed to change as part of the refinement process, so while producing the best set of quick-and-dirty requirements possible is desirable, they are still quick-and-dirty.
The Refinement phase is best handled as a series of small working groups to drive out the TBDs, expand on areas that aren’t sufficiently defined, and answer questions, followed by individual systems engineering efforts to codify the results into good requirements.
At the beginning of the Review phase, the requirements should be well past the 90% mark. All TBDs should have been filled in, and all questions answered by this time. The intent of the Review phase is to bring back a clean set of requirements for review from the interdisciplinary group with focus on identifying cross-functional requirements that might have been missed in the focused groups of the Refinement phase. This is also the opportunity for members of the group outside systems engineering to ensure that the requirements are clear and understandable to them in the manner intended. The bulk of the work should be done as individual reviews, with meetings among parties with conflicting feedback to work out the best way to revise the requirements.
The Approval phase is mostly a formality. Before the this phase, all parties should have had a chance to look at, review, and request changes to the requirements. This phase is therefore just the official signing-off on the requirements and release for development.
While the time taken for each of these phases varies significantly with the complexity of the product, clarity of communication, thoroughness during reviews, and availability for reviews and meetings, the time spent can roughly be broken down into the following percentages:
While the actual percentages may vary, the above numbers give rough guidelines. Expect to spend most of the time in the refinement phase in a series of small working meetings, phone calls, or email correspondence.
While marking something as “TBD” is a good, quick way to keep the meeting going during Elicitation, TBDs generate confusion and uncertainty during development, the effects of which can be just as bad as not having any requirements at all. It is important that TBDs are rigorously filled in during the Refinement phase, performing any necessary tests, studies, or research necessary to get to a good, defensible number. Avoid the temptation to “make something up” or “put in a placeholder.” Remember, one way or another, the systems engineering will be done, and if the groundwork is done at the time during requirements development that it’s expected rather than putting it off for some other time, it will allow the rest of the project to flow much smoother.
Wide, Then Deep
Customers can sometimes be fickle in their desires. The specific reason could be lack of understanding of their customer base, the technology used in the product, regulatory controls, or a combination thereof. Regardless of the reason, easily a quarter of the requirements developed early in the design are almost guaranteed to change. As a result, when developing requirements, focus on broad, shallow requirements first rather than spending a lot of time drilling down to the nth degree on individual items. This is the philosophy of Wide, then Deep. If the customer decides it no longer wants a feature and that happens to be the feature that’s been drilled down, then all of the time associated with that feature was wasted. If, on the other hand, the bulk of the effort was spent creating requirements for broad swathes of features, then only a small portion of the effort was wasted. In general, get the broadest strokes identified first, and then, starting with the most stable pieces of the design, begin adding more and more specificity to each feature. The following figure gives a graphical depiction.
The first pass occurs during the Draft phase and contains vague descriptions of what the system should do. While these requirements are not at all “good” or sufficient, they at least give someone approaching the product a high-level idea of what the system is supposed to do. The first pass might not contain all elements of the design. As shown, the requirements for some of the nice-to-haves are not even started in the first pass.
The second pass could occur during internal review during the Draft phase or during the Refinement phase. Here, the requirements for the core features—those that the system cannot operate without—are developed a bit, and new requirements are added to fill in missing holes. Avoid the temptation to completely drill these requirements down at this phase, as developing requirements for other features of the system may affect these. Preliminary requirements for nice-to-haves might also be identified as part of thinking through the core features.
In the third through fifth passes that occur during the Refinement and Review phases, the core features are fully developed, and non-core features are elaborated on and drilled down. These need not necessarily be developed to the same level in precise parallel, but like tightening a wheel onto a hub, it’s good to spread the effort around to avoid having one feature leave the others behind, only to be completely changed due to necessity from another feature.
In the sixth pass, which may occur long after the other passes and sometimes as far out as the Revision phase, the final requirements are identified for the nice-to-haves.
Note that the figure above is just an example. It may be possible to identify all the requirements fully in just one or two passes, or it may take a dozen or more. There is no magic to the number six; use as many passes as it takes while striving for efficiency.
Always ask, “What if?” When addressing how the system should work, consider:
- What if the user inputs something invalid?
- What if there’s a failure in some part of the system?
- What if something the system was supposed to interface to (network, disposable, peripheral, etc.) isn’t available?
These questions are also directly applicable to risk management activities and can help identify mitigations required to maintain the safety of the system. Begin asking “what if” in the Elicitation phase and make heavy use of it during the Refinement phase. By the beginning of the Review phase, the question should have answers to all aspects of the product slated for implementation. Nice-to-haves that won’t be implemented right away might still have open questions, but certainly all what-if scenarios associated with core features should have satisfactory, complete answers documented as requirements.
What, Not How
Remember that the purpose of a requirement is to describe what the system should do, not how. If you find your requirements dictating architecture or implementation, take a step back and think more open-mindedly about how the system could work. Don’t worry too much about this during the Elicitation or Draft phases, but focus heavily on it during the Refinement and Review phases. The more abstract a requirement is, the less likely it will need to change if the implementation changes, and the more freedom it gives to developers to choose the very best implementation for the need.
This guideline is one of the trickier ones because in some cases, the implementation must be a certain way in order to interact with another system component, whereas in other cases, several different implementations could all achieve the same goal. For example, a requirement could exist stating that the system shall enumerate itself as a USB mass storage device on connection to a PC. If end-users have dictated that they must have USB connectivity and that other forms of connectivity (Bluetooth, Wi-Fi, etc.) are not acceptable, then the requirement should stand as it is. However, if the users only want to be able to obtain data from the device, then consider rewriting the requirement more abstractly to allow developers to choose the best implementation, e.g., requiring that the system transmit the file upon a user request to do so.
Further complicating the above scenario are other factors, such as transmission speed and whether a wired connection is acceptable. Constraints placed on the design by user needs should be incorporated into the requirements, and those constraints might drive the implementation in a certain way, such as a high data rate ruling out Bluetooth or the need to communicate wirelessly ruling out USB.
A Rose by Any Other Name…
While it is important not to dictate implementation when defining requirements, systems engineering must develop a model of how the system works. This includes establishing consistent terms used when describing the device. The overall goal should be to make it easy for developers, clients, management, , and everybody else associated with the project to talk about facets of the product in a way that is commonly understood.
Consider a case where a system:
It is cumbersome to describe the tasks of item 1 as “the mode of the system where it readies itself for use”, the tasks of item 2 as “the mode of the system where it does its intended function”, and the tasks of item 3 as “the mode of the system where it cleans up after performing its intended function.” Some concise, simple naming conventions could quickly reduce these to 1) Initialization, 2) Operate, and 3) Clean-Up. By establishing these terms upfront during the Elicitation, Draft, and Refinement phases (earlier is better) and getting buy-in from the different functional groups (customer, software development, hardware development, management, etc.), systems engineers can build the communications infrastructure required to efficiently discuss the product as it increases in scope and complexity.
The last point cannot be emphasized enough. In keeping with the concepts from the “Ivory Towers and Dull Meetings” section, systems engineers should not invent terms and then shove them down the throats of the rest of the team; however, systems engineers should identify commonly used concepts and give suggested names during the Elicitation and Draft phases to get the discussions started about names on which the team can agree to standardize.
Once terms have been created, systems engineers should carefully define those terms and keep them someplace handy; all documentation that uses the identified concepts should use the same naming. This greatly reduces the learning curve for someone new to the product, including auditors.
Naming and modeling consideration should begin immediately in the Elicitation phase, and this is an excellent opportunity to begin to get buy-in from the customers. Further naming and modeling should be addressed during the Draft phase and the earlier part of the Refinement phase. By the middle of the Refinement phase, the names and models should be pretty well-defined.
Sanction vs. Sanction
Merriam-Webster defines a sanction as “the detriment, loss of reward, or coercive intervention annexed to a violation of a law as a means of enforcing the law”, but also as “explicit or official approval, permission, or ratification”. How is it that the same word can have nearly opposite meanings?
When creating terms, be careful not to overload them, and be careful to avoid overusing words that are reserved in the product’s industry. For example, the term essential performance is defined by IEC 60601-1 that is used pervasively in the medical device industry. Using that term in a medical device to mean anything other than the definition established by the standard is asking for confusion and misinterpretation when a person familiar with the standard sees the word in a different context and assumes it means something other than what was intended. This applies anytime a term is used to mean more than one thing. Save the team the trouble and be careful to choose terms that are unique enough to avoid overloading.
A Picture’s Worth…
For this section, consider the UI state diagram to the right. The challenge is there to write a set of requirements in words that conveys what the system must do—without the benefit of the diagram—in a way that is clear & easy to understand, and that will be consistently interpreted by everybody who reads the description.
The diagram is a very simple state machine. A more complicated machine might have dozens of states and scores of transitions. The complexity of describing it in words increases factorially with each new state and transition, and using a diagram can visually present the information much more quickly and intuitively than pages and pages of requirements.
State transitions are not the only good application for diagrams. Describing the look and feel of a UI and depicting the system components and their interactions are also great applications. In short, diagrams are extremely powerful at conveying ideas and terms of all kinds. Use them liberally where it is appropriate to do so.
Diagrams can become useful almost immediately during Elicitation to convey the modes of the system and a simple block diagram of the system and its components. Even if the diagram is hand-drawn on a piece of paper or a whiteboard, it should be captured and used in the Draft and Refinement phases.
Put Your Stone Tablets Away
From experience, it is easy to get attached to the requirements one has written. Just as a circuit design is a reflection on the circuit designer or a software module is a reflection on its creator, requirements are a reflection on the author’s skills as a systems engineer. However, it can take a while to learn that unlike a circuit design or a software module, how requirements are interpreted is just as much a reflection on the people who read them as it is the author. Software will be interpreted precisely one way by the compiler, and a hardware design will be interpreted precisely one way by a PCB fabrication and assembly shop. Requirements, on the other hand, must be interpreted by each person who reads them, and each person comes with a different perspective, and there is no “final proof” that requirements are perfect. If a systems engineer writes some requirements and hands them to someone, that person will probably interpret them at least somewhat differently from what was intended. If the two of them hone the requirements so that both of them interpret them exactly the same and then hand them to a third person, that person will likely interpret them at least a little differently from the way the two intended. Unless the systems engineer gives the requirements to every single person who will ever have to interpret them and the scores or hundreds of people form consensus on each word and punctuation mark in each requirement, the requirements will always be a work in progress, and that situation is neither practical nor useful.
Further complicating this is the fact that customers change their minds. No sooner would the hundred people reach alignment on the wording for the requirements than the customer would suddenly want to add a new feature or change or delete an existing feature, starting the process all over again.
The point is, requirements change from the day they are first drafted in the Elicitation phase until the product has gone end-of-life and is no longer supported, beyond the end of the Revision phase. Avoid the temptation to get hung up feeling that since a requirement had to change, it reflects poorly on the engineer who wrote it. Systems engineering is, among other things, a discovery process, and identifying that a requirement needs to change because it is not clear to a new reader or because the customer needs changed is just part of the discovery. Do, by all means, learn from the experience to produce better requirements on the first draft next time, but don’t take changes personally.
The Times, They Are A-Changing
As mentioned in “Put Your Stone Tablets Away”, requirements are constantly changing. So, too, is the system design. While a good set of well-abstracted requirements should be fairly resilient to changes in the design itself, the underlying concepts may change as implementers discover alternative ways to model the problem than was originally modeled in the requirements. While the bulk of a system engineer’s job is done at the end of the Approval phase, there will almost always be a slow, steady trickle of changes and clarifications that arise during development, and to avoid relying on obsolete knowledge, the systems engineer must stay abreast of changes in the project throughout the Revision phase. That doesn’t necessarily mean attending every design meeting, but periodically checking in with the design team to see if there are any questions that need to be addressed by the customer, requirements that need to change, or conceptual model shifts that need to be documented will help to keep the systems engineer up-to-date with the project and the documentation useful and relevant to new team members.
Systems engineers are not far removed from servers at a restaurant. They must take customers’ initial orders and offer their expertise to help their customers decide what they want during Elicitation. They must relay the information back to the kitchen (the design team) in a way that clearly conveys what the customer wants so that the cooks can make what the customer ordered during the Refinement, Review, and Approval phases. They must check in periodically to make sure that things are going the way the customer wanted and interface with the design team to steer the product in the right direction when the customer makes a clarification or requests a change during the Revision phase.
Describing a medical device requires far more documentation than some coded entries scribbled on an order pad, and this is where the service aspect of a systems engineer’s job becomes all the more important. Not only is the company’s customer a customer for systems engineers, but so is the design team, and a systems engineer’s focus should constantly be, “how can I make this easier for my team and customers to understand?” The systems engineer needs to check in with the customer periodically, but also with the design team to ensure that the requirements written are still accurate and easy to understand.
Just as a server is judged on how easy and pleasant he or she makes the dining experience, so, too, is a systems engineer. Striving to make the design experience pleasant for all by streamlining the communication among the affected groups is what makes a great systems engineer.
This blog has identified several ways to make the onerous and oft-underappreciated task of requirements development a little less onerous and a lot more streamlined. By following the procedure described in the “Requirement Development Process” section, a development team can quickly progress from requirements elicitation and drafting into refinement, review, and approval, offloading the bulk of the work onto systems engineering while keeping all of the interested parties involved and aware as the process advances.
This blog also described several strategies for requirements development that produce better output in less time. While some strategies, like “Ivory Towers and Dull Meetings,” “Terrible TBDs”, and “Wide, Then Deep” address procedural considerations to ensure that time is spent efficiently and risk associated with change and uncertainty is driven out in the appropriate phases of requirements development, other strategies such as “Just Do It”, “Put Your Stone Tablets Away”, and “Service First” deal with the attitude towards requirement development.
This holistic strategy—focusing on both the mechanical aspects of how to streamline the process and the interpersonal aspects of systems engineering as a whole—reflects the systems engineering perspective taken at Realtime: we know that taking a holistic approach to any problem—be it developing your company’s next product or improving our own requirements development processes—addresses the issue more completely than taking a narrow view that only focuses on one small piece of the problem. We understand the importance of systems engineering in the product development life cycle and know how to elicit, draft, refine, review, and approve requirements that will give our design team its best foot forward when we begin development and how to revise the requirements after development has begun to keep them relevant and accurate. Finally, we recognize that things will change along the way and understand the importance of maintaining dialog with our customers throughout the design.
With its extensive experience in systems, electronics, software, and test engineering, Realtime has worked with many customers to help them define their products, prototype their designs, and turn their concepts into reality. Contact The Realtime Group today at 972 985-9100 and let our engineers help bring your concept to life!