The Requirement Editor and Viewer utility is designed to show the relationship between 2 levels of Requirement (Level N and Level N-1). Depending on the client set up, the links can be customised so that the order of the N-1 requirements can be changed so that they follow a logical progression, or a particular scenario. This tool has proved to be of immense value in presenting requirements to a review panel or the client for formal endorsement.
DOORS is particularly valuable for Progressive Assurance and for demonstrating that a requirement has been fully verified and validated. As well as showing the relationship between requirements at different levels, it is possible to link Test Results and other forms of verification evidence to all level of requirements via ‘Verification Goals’. A Verification Goal is essentially how you are going to prove that the requirement has been met. Typical outputs from the Verification Goal modules will include the Verification and Qualification Plans and Verification Cross Reference Matrices (VCRM). Note different companies will use different terminology but the principles will be the same.
The tool has been designed as both an editor (and therefore only presenting to the user those fields that can be modified) and as a viewer. These are fully integrated so that it is possible to navigate to a particular requirement in the current module using the tool, then view and/or edit attributes and then switch to the viewer to see the impact of making any changes. Either the lower level requirement or the verification attributes can be shown by a click of a button.
Requirement Editor utility
The user will be able to add or remove links from lower level requirements by the use of a search popup that interrogates the lower level module structure.
Another feature lacking in classic DOORS is to show the interrelationships between levels of requirements.
Working in conjunction with the requirement editor, CiGi Technology have produced this viewer that shows how requirements at a lower level satisfy the upper level requirement which is the subject of interest. The user can easily switch from Editor to Viewer and back again.
Example of a Requirement Traceability view
The lower level requirements are shown together with the type of relationship in the traceability from the lower level. Also displayed is the requirement ID and the heading above each requirement. This view is particularly useful for navigation around the requirements.
Either the lower level requirement or the verification goals can be viewed by a click of a button.
Sometimes requirement authors can get carried away and write
long verbose requirements or even longer descriptive text. These can cause
quality issues and more often than not can be easily split into smaller chunks.
This aids readability.
Over long requirements can imply that the V&V would be similarly
overly complicated.
Layout DXL script to identify oversized objects
This DXL script will identify over long objects (the size is
defined in the layout script) in a layout DXL column. All objects are
considered whatever the type, but tables are only displayed as a single row in
order to reduce the clutter.
If the size is below the required number of characters, then
it is excluded from the display by a filter. If not, then the number of
characters is displayed.
The reviewer/author can then split the object at a convenient location and the filters
can be reapplied.
As the project progresses then the requirement scope and
therefore the requirement text may change.
Occasionally, a requirement can become a description, or a
description can become a requirement. Worst case scenario is that the author
can forget to set the Object Type (it happens !).
We need to flag these mismatches so that only the true
requirements can then move forward for the completion of the verification and
validation attributes.
DXL script to apply a filter for Object Text and Object Type mismatch
This DXL script simply applies a filter for :
all requirements (as defined by the Object Type)
that do not have a “shall”
Often at the start of a project some of the design criteria, limits or ranges are not known and “To Be Defined” (TBD) or “To Be Checked”/”To Be Completed” (TBC) are used in place of, or together with, the proposed values. For example, the value maybe defined but followed by (TBC).
As the project progresses, then more detail will be
designed, and the requirements can be completed without these limitations.
What would be very useful is a DXL script to identify these
requirements which have been annotated in this way.
DXL script to apply a filter for TBD/TBC
This DXL script simply applies a filter for TBD or TBC for
all requirements (as defined by the Object Type).
Spell checking is always an issue in requirements. It is
important that all spelling mistakes are removed before a requirement is sent for
review so that the reviewers do not spend time correcting typos and forget the
technical stuff.
Layout DXL script to identify spelling mistakes
This script uses the spelling functions of DXL and will identify any misspelt words in a layout DXL column.
It does not prevent mistakes as you type like Word but if
combined with a view to filter on ‘not equal to “OK”’ then it is a simple task
to quickly spell check and correct. The current implementation is for English (UK)
as this is the most common language for requirements but the DXL script could
be adapted for other languages.
Perhaps one of the most important quality attributes necessary for a requirement is to be able to verify the requirement. Some of the phrases and words that we use in every-day language, because they are ambiguous or cannot be verified, should never be used in requirements; some should only be used in exceptional and justified cases. There are also non-specific phrases, pronouns, indefinite pronouns, unmeasured quantifications, indefinite temporal keywords and other grammatical constructs that also should never be used in a requirement.
Layout DXL script to identify banned words
This DXL script will identify any banned words (or rather terms that should be avoided) in a layout DXL column.
It does not prevent mistakes as you type but if combined with a view to filter on requirements and ‘not equal to “OK”’ (which is the default) then it is a simple task to quickly identify areas of concern and correct. The banned word list is currently hardcoded into the DXL script but it could be enhanced to read the list from a specialist module to provide more visibility and ease the maintenance task. The list could be tailored for individual companies.
It is interesting to note that IBM have recently launched
their own Requirements Quality Assistant for DOORS Next.
“Using Watson Natural Language Service and pre-trained AI, the Requirements Quality Assistant has 10 built in quality indicators designed to be consistent with guidelines from the International Council on Systems Engineering (INCOSE) and NASA for writing complete, clear and testable requirements to accelerate your review process, increase requirement quality and reduce training for junior requirements engineers.”
Although this DXL script is not as sophisticated as IBM’s, it nevertheless will highlight words that should be avoided – and at over 150 terms, our list is longer than in the INCOSE guide!
It is very common practice to introduce a hierarchical breakdown of a project according to the products or systems. This is known either as a Product Breakdown Structure (PBS) or System Breakdown Structure (SBS). There are a number of ways to introduce this into the DOORS database. You could use an attribute in every module with an enumerated list containing all the PBS values. The disadvantage of this approach is that when you have to make a change to the list (and this is more common than people think) then the type has to be changed in every module. Whilst this is easy to achieve using the Module Administration tool (see Module Administration utility), the second disadvantage is that you cannot actually see a hierarchy in a flat list of elements. You also cannot see a combined list for all modules. So, if you wanted to see requirements allocated to System X then you would have to search all modules and somehow collate the results together.
A more effective approach is to build a PBS into a standalone module. This has a number of advantages:
The
hierarchy is immediately obvious;
The
list can be easily changed;
The
item can have additional attributes such as a description;
By
linking requirements to items in the PBS it is possible to display the values
as a DXL attribute; and
Most
importantly, by viewing the requirements from the perspective of the PBS you
can see the impact of making a change to the PBS– before making the change. Impact
analysis is greatly enhanced.
The principle can
be adopted for any hierarchical list. For example, hazards can be broken down
into causes.
The same principle for a PBS can be applied to a
Verification Breakdown Structure (VBS). In fact, using DOORS as a relational
database, it can be applied to any form of enumeration (Organisation Breakdown
Structure (OBS) or Work Breakdown Structure (WBS) although over-use can result
in spaghetti-like links.
The Verification Methods would be defined in the Verification Breakdown
Structure, or its equivalent, and therefore it is very easy to identify all
requirements that will be affected by a single Verification Method by looking
at all the links from the VBS module. This permits the use of multiple
Verification Goal modules structuring and ordering the Verification activities
according to operational rather than functional needs. This approach makes the
generation of the Test Procedures/Test Schedules very controlled as the modules
provide the framework.
Another point to note is that there should always be a
strict data model enforced within the database with reserved words for the link
relationships. More details on how CiGi Technology can help you produce a data
model can be found in Consultancy
Services.
Example VBS
DXL
Attributes can be used to show the results of the link.
It is commonplace to see in a requirement statement the
phrase “in accordance with xxx” where
xxx is the title of a reference or “ … in accordance with Reference nnn” where
nnn is a unique number assigned to a reference. How is this managed in DOORS so
that the references are controlled and that any change is propagated through
the whole of the project?
In particular, it is very important to know the issue or version referenced from a requirement as any change in content may significantly affect a requirement and initiate an impact analysis (that determines what would be the impact of changing a reference). Unfortunately, there is nothing readily available in DOORS Classic that can help.
However, what we can do is to build a reference or evidence
list.
A reference list
would contain all the documents that are referenced by the requirements. As
well as the mandatory attributes such as the document reference number, title
and version/issue we could add additional information such as the document
type, who authored the document and when it was issued.
Example References
The question of what requirements would be affected can be
automated using DXL to provide the identification of where it is used. Thereby
considerably reducing the amount of time that the management of external and internal
referenced documents would take for an organisation.
An evidence list has similar properties but it is used to
identify documents external to DOORS that are used in the evidence trail. For
example, Standard Operating Procedures, Test Cases, Test Reports etc.
Example Evidence List
Additional attributes may include Verification or Validation identification and external hyperlinks to a document repository. The important thing to note is that the traceability from evidence to the requirements is continuous.
In these examples we are using an internal repository module/table. We could have alternatively used direct traceability links such as provided by Open Services for Lifecycle Collaboration (OSLC). Support on OSLC synchronisation to external document repositories such as Aconex, Documentum or TeamBinder is also available.
It is extremely useful if Abbreviations are defined either
at the Company or at the project level. This will prevent misunderstanding if
the same abbreviation has different meanings on different projects.
An example of this
could be ‘PBIT’ which could mean either “Power up BIT” or “Periodic BIT”. A
misunderstanding in the use of this term between teams could lead to totally
different functionality resulting in significant interface issues and rework.
Example Abbreviations
In this type of
implementation then a sophisticated DXL Attribute is used to display the ‘Where
Used’ values – there are no links involved.
It is interesting to note that this functionality is already
available in DOORS Next.
A data repository is always needed because words can have
different meanings in different contexts. They also can be highly specific:
Identification – A user (person or
system) must supply an identifier and/or the system must in turn supply an
identifier to the user so that the user knows that he is accessing the right
system.
Authentication – The identity of the user must be authenticated (i.e.,
verified so that we know that the user is who/what the identifier is associated
with). That is, authentication is the verification of the identity assigned
during Identification.
Authorization – Once a user has been identified and
the user’s identity has been authenticated, the user can use the services and
access the data that the user is authorized to use and
access. This can be done by membership in a group or done on an individual
identifier basis.
Use of italics and/or Capitalisation of a word is
often used as a means of indicating a glossary item, so that it is clear to the
reader that it is not just a word in a sentence, but it has a defined meaning.
A parser can now check the specification for undefined terms.
A glossary in a requirements specification, and which is
project wide, is absolutely essential as it provides the precise definition of all
terms.
Example Glossary
In this type of implementation then DXL Attributes are used to display the ‘Where Used’ values – there are no links involved. As with the Abbreviation terms, then this functionality is already available in DOORS Next.
For information on a DXL Script that pulls all these features together then click here.
