Do Requirements need a Heading?
Abstract: Did you ever question the rationale behind why IBM DOORS objects in a Formal Module have an Object Heading and an Object Text and why there is a distinction? Well, the answer, as usual, can be found in the SysML notation. Today, let's explore this simple yet highly significant topic.
What does SysML say?
SysML Specification Chapter 16.1:
A requirement is defined as a stereotype of UML Class subject to a set of constraints. A standard requirement includes properties to specify its unique identifier and text requirement. Additional properties such as verification status, can be specified by the user.
Nothing has been mentioned about a header thus far. However, it is worth noting that the Class element is built upon a NamedElement and, as a result, possesses a Name attribute that identifies the element. This attribute proves to be practical and essential to distinguish each element, particularly within the hierarchical model tree. With this in mind, we can now recognize that a header is, in fact, indispensable when it comes to modeling requirements, as depicted in the figure below.
When applying this approach to Rhapsody, an example of the resulting diagram is shown below. The diagram includes a Heading element and a Functional- and Non-Functional requirement, each accompanied by their respective requirement name, requirement identifier, requirement specification, and two additional properties (attributes) defined by tag values.
How do Requirement Authors typically write?
The question may arise for this article's readers: why does the author emphasize this topic if it seems so obvious? Well, the truth is that many requirement engineers who work with tools like DOORS perform the requirement writing differently. They often write requirements in a typical fashion, as illustrated in the image below.
What is the Problem when writing like the above?
First, let's look at the correct way of doing it, as demonstrated in the image below, where the Object Heading and the Object Text are merged into one Object.
What are the Improvements when writing the proposed way?
A significant improvement lies in the ability to effortlessly and SysML-conform export of the Requirement objects to Rhapsody. This can be achieved by simply utilizing a spreadsheet or the Rhapsody Gateway, resulting in a Requirement Diagram that reflects the outcome. as shown in the figure above. The Object Heading is directly mapped to the requirement element's name, providing a straightforward means of identifying the requirement based on its name in the model tree. Without a provided name, utilizing the Identifier as a substitute might be necessary.
Advantages:
Elimination of individual headings significantly reduces the number of objects. This simplifies the process of maintaining attribute settings for multiple objects and significantly improves readability. The objects are no longer "glued" together, as depicted in the poor example below, where objects on the same hierarchy level are written without a heading.
Below is an improved example where objects on the same hierarchy level are accompanied by a heading for enhanced clarity.
By providing a heading for each object, the navigation through the document is notably enhanced, as there is no longer a need to read the entire requirement text. Furthermore, utilizing filters to focus solely on the headings further improves the efficiency of finding specific requirements, particularly when the object headings are well-formulated. This approach allows for a quick grasp of the requirement content without reading the entire requirement text.
Finally, the traceability in Rhapsody becomes much more comprehensible when linking requirements with meaningful names to corresponding block elements, as opposed to only displaying the ID in the name. This approach greatly enhances the understanding of traceability relationships within Rhapsody, as shown in the figure below.
Summary: This article highlights the significance of accurately writing functional and non-functional requirements in IBM DOORS to enable a SysML-compliant import into Rhapsody. It emphasizes the improvements in requirement readability and discusses the issues that can arise when the Object Text and Object Heading of a requirement are separated. The author's hope is that by adopting this simple yet crucial writing style, the linkage between requirement tools and modeling tools can be enhanced, leading to improved conformity and integration.
The author would greatly appreciate your feedback on this article, especially regarding the insights on writing requirements in IBM DOORS and their import into Rhapsody.
Stay Linked! Stay Curious!