Making the Analysis of Requirements Documents Easier

Language: So necessary for communication; so often the cause of miscommunication. Miscommunication, even simple misinterpretations, can be costly: assembled parts don’t fit, scrap and rework increases, mechatronic systems have unintended bleed-throughs, life and death are at stake.

And it all starts with a requirements document, points out Jordan Kyriakidis, CEO and president of QRA Corp. (qracorp.com). “The foundation of an engineering project starts at the earliest stage of collecting ideas and synthesizing those ideas into a cohesive set of requirements. This communication step is critical, yet prone to human error—introducing inconsistencies, oversights, and ambiguities.”
Exorcising those faults in a requirements document is a dirty job, and somebody does do it. Engineers, trained to be clear, exact and succinct, often find writing frustrating, not their forte. Editing “finished” documents is even more frustrating. 

Till now, reviewing requirements documents has been a manual affair: Somebody checks requirement after requirement for proper and logical decomposition of designs and systems, explicit descriptions, words, syntax, and more. “It’s a big, clunky job that needs to get done,” says Kyriakidis. “Machines and computers are very good at doing the drudgery.” QVscribe from QRA fits the bill. QVscribe is a requirements analysis tool. It combines natural language processing (NLP) with an expert system.

Continues Kyriakidis, QVscribe can “eliminate over half of all design errors before they occur, improving the early stages of requirements documents.” Better, it can “significantly reduce the cost of fixing requirements errors by finding them earlier and faster, and to free domain experts from tedious, time-consuming tasks that waste their expertise.”

The birth of a digital technology
QVscribe is not QRA’s first software product. That honor is held by QVtrace, a model-based systems engineering (MBSE) tool that analyzes and verifies a system design against requirements. MBSE tools are based on precise, mathematically based specification languages and domain models that can be tested and verified. For example, QVtrace uses standard model-based design formats, such as Mathworks-Simulink, Modelica, and SCADE, to confirm designs meet requirements. Where it finds inconsistencies, QVtrace highlights the unmet requirements. 

The precision inherent in MBSE tools leaves no room for catching the ambiguity and errors in requirements documents. “When we first began building QVtrace,” explains Kyriakidis, “we assumed systems engineers would use it to design better models, where fewer design errors would drift and be uncovered during late-stage testing. What we discovered is that at least half of the problems lie with the requirements, not the designs.”

This discovery became the impetus for QRA to develop QVscribe, a tool that would analyze requirements and alert the author of ambiguous, overly complex, and essentially malformed engineering requirements. The requirements for the tool itself include being lightweight, “available to engineers in their current workflow,” and “grokked in seconds.” To do that, continues Kyriakidis, QVscribe turns “syntactic weaknesses into strengths using a visual grading system powered by NLP.”

(Not so incidentally, NLP is the application of computers and AI to analyzing, understanding and even generating languages that people speak, hear and act upon every day.)

QVscribe in action
QVscribe acts like a spelling/grammar checker for requirements documents. Once this add-in utility is installed, it appears as a toolbar icon. Clicking the icon launches QVscribe. First though, some housekeeping is required, which is typically done once: specify the location of requirements in a document, specify the acceptable terminology used in requirements, and identify specific parts of requirements that should not be analyzed. Once these steps are complete, QVscribe “autofinds” requirements in the document. (The engineer can manually confirm all requirements have been included by adding and removing requirement markings as necessary.)

The QVscribe is analysis is based on eight quality measures: imperatives, negative imperatives, options, weaknesses, vagueness, subjectiveness, continuances, and directives. (Engineers can customize QVscribe for the user, project, and company-specific quality triggers and phrases appearing across documents.) This analysis does not come out of a vacuum; it is based on the best practices for requirements documentation from organizations such as NASA and International Council on Systems Engineering (INCOSE). The analysis can also be customized to match a company’s best practices for requirements documentation.

The results of the analysis are displayed in a simple, interactive scorecard, what Kyriakidis calls the “Amazon Five Stars.” This display indicates the “quality” of each requirement by number of stars (one to five). Sorting the quality scores lets engineers focus on problem requirements. Clicking on a requirement listed in the scorecard takes the engineer to the requirement in the document. There, the engineer can see highlights showing the quality indicators that triggered the given score for the requirement. There and within the authoring tool, such as Microsoft Word, the engineer can revise the text of the requirement. Engineers can run the analysis as many times as desired to improve “poor” requirements until all get a 5-star rating. In this way, QVscribe is not only a diagnostic/analysis tool, but also an authoring tool.

Currently, QVscribe is available as an add-in for Microsoft Word and for the document management tools IBM Rational DOORS, a part of the IBM Rational Rhapsody Suite and Visure Requirements Management.

An automotive example
Kyriakidis says both domestic and foreign car manufacturers using QVscribe find it most useful when building something brand new, as opposed to revising some part, assembly, or system for each new model year. Because requirements documents can be formidable—300, even 1,000, pages in their final form, including ancillary information (such as table of contents, version history, and often an introduction)—some companies use QVscribe to rank the requirements in these documents from worst to best, giving the company a better idea of where its risks and liabilities lie. One QVscribe customer farmed the requirements document off-shore to lower-level staff who ran QVscribe, extracted the actual requirements, and created a new, shorter requirements document to review.

QVscribe’s value really shines in the world of mechatronics. Explains Kyriakidis, most new cars now have a rear-facing camera. Put the car in reverse, the camera turns on. The camera’s display is usually part of the car’s entertainment system. If this backup video system senses an object, it applies the car’s brakes. In terms of system engineering, a direct line of connectivity now exists between the entertainment and the braking systems of the vehicle. Conceivably, the requirements for one system could affect the other.

Aerospace, points out Kyriakidis, has the twin concepts of “flight critical” and “mission critical.” Flight critical are the things that if they fail, the airplane falls out of the sky. In automotive, the flight critical systems—driving critical?—would be brakes and the steering mechanism. “Those absolutely have to work. Components can fail, but the system has to work. As [automotive] systems become more integrated, automated and more autonomous, the envelope of what’s ‘flight critical’ grows and starts encompassing more and more of the systems. As that happens, engineers have to develop and prove everything to a far more rigorous degree. That all starts right from the requirements themselves.”