Welcome back to part three of my specification building series of blogs. If you’ve read the preceding blogs then you should be well versed in specification building up to the constraint section of the specification. The goal of this series is to demystify using the System/Segment Specification Report. My hope is that this helps you understand how to model in GENESYS in a way that will allow the report to work as it’s intended and build a truly model-based specification for you.
Let’s finish our look at the GENESYS specification and cover the 3 remaining sections. Buckle up – we have some verifying to do! The last two major sections of the standard specification template are the Qualification section and Requirements Traceability sections. Optionally, you can include the behavior diagrams as an appendix to aid in the understanding of your specification (highly recommended).
Let’s start with the Qualification Provisions section. This section by default outputs the VCRM. No, that’s not some kind of medical condition – it’s the Verification Cross Reference Matrix. This section outputs the systems proof, or how you verify the requirement statements made throughout your model that were pulled into this specification. The GENESYS meta-model separates a requirement statement (remember requirement “shall” statements can be written into the function or any other specification entity’s description…) from its verification aspects. Verification aspects define how you are going to verify the requirement.
Typically, a verification requirement requires 5 pieces of information to be complete – the Objective of the verification, the method of verification (typically Analysis, Inspection, Demonstration or Test), the Environment the verification is to be performed in, the success criteria for the verification, and if there are any special conditions of the verification that need to be conveyed. These 5 aspects (Objective, Method, Environment, Success Criteria, Special Conditions – OMESS!) are entered in the verification requirement which is then related to the function, item or other entity that is the specification entity (the entity where the “shall” statement is written).
In the Qualification Provisions section of the spec, GENESYS will pull the requirements that were found, output in the preceding sections and build a table with their verification information. It takes the stored list of requirements and then follows the “verified by” relation to access the verification aspects of the requirement. The table it builds consists of the Requirement name, the verification method, the verification level, the verification status (typically – Not Yet Planned, Planned, In Progress, Completed – Satisfactory, Completed – Unsatisfactory), and finally it follows the relation from the Verification Requirement to the Verification Event information for that Verification Requirement. This completes the VCRM table, and the qualification section. The verification aspects of your model can be further expanded in test plan documentation that you can generate from the model – perhaps the subject for another blog?
The final major content-containing section of the specification is section 5, Requirements Traceability. This section contains the traceability information from the requirements that were output in this specification to the higher-level elements they’re descended from. Just like what happens in the Qualification section, the report will iterate through the set of requirements that were gathered during the execution of the report, and output each of their parent requirements.
The report follows the “refines” relation to find the parent requirement, and then outputs the requirement name. The report will also out any “specifies” relations, in other words, if a requirement specifies a component (aka constraint) the component name will also be output in this section along with any requirements that this requirement refines. If the requirement has no parent relation, the report will output “System Design Decision” for the traceability. This makes sense when you consider that, if the requirement has no parent at this level of the specification tree, then it must be a design decision at this level. Traceability in GENESYS can mean more than just Requirement to Requirement, it includes traceability to different aspects of your architecture.
The final regular section of the specification is a Notes section. This section covers the acronyms, abbreviations, and a glossary of terms used in the specification. It is created from following the “uses” relation to entities in the Defined Term class from the starting document that was typed as System/Segment Specification which is the document this report is running against. The defined terms that are found are then placed in the appropriate section based on whether or not the acronym attribute of the defined term is filled out or not, and then sorted alphabetically.
After the regular numbered sections, the SSS report will output what I feel is one of the most important sections, and one that is so often overlooked in specifications. The report will output the behavior diagrams in an Appendix. Behavior diagrams should be the basis for your derived requirements in your spec. You should build out the behaviors, capture the decisions needed by your system, and write the functional requirement statements directly in the function entities. If you’ve done that, then your spec will truly be model based. If you’ve put in the work to really build a model-based spec, and then leave out the diagrams that capture the visualization of the needed behaviors, then you’ve really missed an opportunity to help the spec reader understand the behavior of the system that’s being specified. Include the behavior diagrams!
The report will by default insert the behavior diagrams for the functional requirements it found during execution of the specification report. If the requirement statement was written into the function, then the function entity was kept in a list of requirement sources. This section iterates through that list of requirements, looking for anything in the list with a class type of Function and a “decomposed by” relation. When it finds this combination, the report knows it has found a source of an Enhanced Functional Flow Block Diagram (EFFBD) that it will output in Appendix A.
So, that covers the built-in GENESYS System/Segment Specification report in some detail. My hope is this blog will help further your understanding of this extremely useful report, and will enable you to try it out and make the leap to a truly model based specification. Don’t just write your specifications, model them.
If you’ve taken away one thing from these posts, I hope you’ve seen that in GENESYS system specifications are not at all about outputting requirement class entities. The model is so much more than requirement entities. The specification is built from the attributes of many different classes of entities in the GENESYS database. Building out the behavior model, capturing what your system needs to do at a specified level, capturing the decisions and logic of your system in a form that aids understanding (Enhanced Functional Flow Block Diagrams or Activity Diagrams) is crucial in developing a good specification. Without the model to guide this process and serve as the structure of the specification, you’re just pulling in requirement statements. And from where? From the heads of all your different engineers? What a great way to gather up all those engineers’ pet rocks and place them randomly in your specification. But you can do better that that! You need to do better than that! Model your system, and let the specification be developed from that model, get that info out of engineer’s head in a format that aids in understanding. Now, go forth and specify!
