Dec 082015
 

TornadoThis is not a new question. We have been struggling with managing traceability to standards for as long as we have had the concept of traceability to standards.
In the DOORS Classic World we had a few options, and we still have those options with DOORS Next Generation, but we also have a couple of new options. I am going to look at this fresh and go over the pros and cons for the various methods in DOORS Next Generation.

I will look at the following methods:

  1. Attributes
  2. External link
  3. Separate module and link
  4. Separate module and reuse
  5. Separate module, reuse and link
  6. Glossary terms
  7. Glossary and link

1. Attributes

The simplest answer is to have an attribute to store the details of the standard that is being addressed by the requirement.

Pros: Easy to set up

Cons:

  • No consistency
  • Difficult to search

2. External Link

A link to a standard held elsewhere can be added.

Pros:

  • If there is an OSLC interface then an OSLC link will add value.
  • No need to repeat any work in translating the standard for a new tool.

Cons:

  • This is most likely to link to a whole standard, hence coarse granularity
  • Any change of the location of the standard will result in a broken link.
  • Manually adding a non-OSLC link will make searching for the traceability difficult.

Separate Module

Creating a module for standard or standards is not really a single method. You can create a single module to hold all the standards – probably just the title and a description. You can create a single module for each standard, and populate it with either the table of contents, or the full standard text.

My personal preference here is to opt for the Table of Contents. Bringing in a full standard is difficult if it is in .pdf format as the conversion tools generally are very expensive, or leave a lot to be desired. There are also copyright issues with many standards which preclude this option. Being able to link to a section of the standard via the table of contents gives a reasonable level of granularity to the traceability without infringing copyright.

3. Separate Module and Link

Having created the module for whichever approach you choose, you can then link individual requirements to artifacts in that standard.

Pros: Traceability to the level of granularity at which the standard is recorded. From each artifact in the standard, you can see the links to requirements.

Cons:

  • Care should be taken to create the correct type of link (‘complies with’ rather than ‘satisfies’)
  • Links should be made to the artifact in the module not the base artifact, so the module containing the standard should be open for drag and drop linking.

4. Separate Module and Reuse

Having created the separate module as before, this time we will reuse the artifacts in the requirements module. This gives the appearance of repeating the information in the context of the requirements, but in fact is a genuine reuse with no additional storage, or maintenance overheads.

Pros:

  • The relevant detail of the standard (name, section heading, or content) is visible in the context of the requirements module.
  • The places where an artifact is used and reused can be seen in its ‘Where Used’ section.

Cons:

  • The requirements module is cluttered with detail at a different level of abstraction.
  • Only really good for linking sections of a document to a standard. Linking individual requirements would result in alternate requirement, standard, requirement, standard and make the module twice the length it should be.
  • Visibility of traceability is not simple, there is no easy way to display that a requirement is a reuse from elsewhere. An extension of this is that reporting on that same traceability is also not simple.

5. Separate Module, Reuse and Link

Similar to above, but when the artifact from the standard is reused, a link is created back to the instance of the artifact in the standards module.

Pros:

  • Reporting and visualization of traceability are now simple.
  • All the pros from the section above.

Cons:

  • An additional step has been added to the insertion of the reference in the requirements module.
  • The first two cons from the section above still apply.

6. Glossary

This is partly the same structure as the separate module idea above. Glossary terms are created for each item (whole standard, section, or detail paragraph). These glossary terms would then be presented in a glossary module to give an overview. As a standard, or part of a standard is referenced, the glossary term will be used in line with the requirement text. The rich hover text will give more detail. A good approach here might be to use the standard number and paragraph number as the term, and the text as the definition.

Pros:

  • The references to the standard are in line, and can be in a separate artifact if required to include the rationale statement.
  • The extent of the usage of each standards artifact can be seen from its Links tab.
  • Adding the term can be done with the use of Ctrl+Space while typing.

Cons:

  • You have to create glossary terms, which takes a little longer than just a text artifact if the rich hover text is going to add any value.
  • Terms need to be unique, so several standards all with a section titled ‘Introduction’ will need to be differentiated. There may be more substantive sections that have duplicated titles across standards.
  • Traceability from the requirements module back to the standards is not easy to visualize, as this does not show up as a link. As with the reuse example above, reporting is also an issue.

7. Glossary and Link

Similar to the Glossary option above, but whenever a term is inserted, a link is made from the requirements artifact to the term definition.

Pros:

  • Reporting and visualization of traceability is now simple
  • Other Pros as above

Cons:

  • An additional step has been added to the insertion of the reference in the requirements module.
  • The first two cons from the section above still apply.

Summary

All of the options here can be useful in the right situation.

 

  1. Attributes: Good for quick and dirty linking where consistency is not required. This is a bonus, not part of a controlled process.
  2. External link: Good for linking in to well controlled documentation held outside of DOORS Next Generation. Not part of a full bi-directional traceability solution unless as solid OSLC link exists.
  3. Separate module and link: Good for getting the job done simply. The level of granularity is flexible, reporting is simple. User Interface (UI) peculiarities will be a matter of taste and familiarity will likely make this better not worse.
  4. Separate module and reuse: Good for showing the standard in the context of the requirements. Good for coarse granularity only, traceability to sections of requirements, not individual requirements. UI will be a little more work intensive than for 3.
  5. Separate module, reuse and link: Good for when 4. above is not quite good enough on reporting and the users have a little patience left for another step when adding traceability to a standard.
  6. Glossary terms: Good for bringing the traceability into focus in the requirements. By showing the standard number and paragraph number, a large amount of text can then be made visible on rich hover. Best for complicated, or unfamiliar standards. This is probably the easiest UI experience.
  7. Glossary and link: Good for when 6. above is not quite good enough on reporting. The UI is a step harder here, as a link must be made for each reference. This is still not hard to do, but does take a little time, a few clicks, but an additional thought process.

Recommendation

Consider what you want out of the traceability, what granularity, and what sort of reporting. Also consider your users, both the people entering the standards and those referencing the standards. For a controlled process, I would recommend starting with either 3. or 6. and refining from that point.

There are many ways to address this particular problem, I think I have covered the major ones here, but do feel free to comment below with refinements, alternatives, or other comments.

 

Leave a Reply