Following on from the Information Architecture Workshop series, I want to show an example of how some of that information should be documented. A comprehensive document should be made available, but also a summary document for quick reference and guidance. Some years ago we produced a quick reference document for a generic schema and process, and that is still valid with the current version of DOORS.
The document consists of two double sided pages, one for process and one for the schema. A draft version can be downloaded from here. The formal modules are shown along with their relationships in terms of link modules. There is some detail on the attributes used in each formal module type, including a list of enumerations for the enumerated types. User roles are described with their access permissions. Finally a state transition diagram for the Status attribute is shown.
This is a simple example, and does not show relationships to other tools and processes. In practice there is usually something much more complicated in place, but this type of information will sit at the heart of even a complex structure. The trick is not to try to put everything on one diagram, but to create manageable, useful, subsets of the information.
If you already have a DOORS project and want to reverse engineer this type of document, it is entirely plausible to do so, but bear in mind that if this didn’t exist as the project was created, there will not be the same sort of consistency that comes from a planned structure. Running DXL scripts to extract the attribute and link information is possible, although those scripts need to be written and tested first. The scripts will produce data in a form that can then be processed into something meaningful.
This kind of reverse engineering exercise is sometimes needed, but can be expensive in terms of effort, and (if done properly) will yield results that show the true status of the database, which may not be a pretty picture at all. Some projects will just want the information, others may try to inject some consistency by renaming attributes and views. There are many pitfalls in this approach, but in some cases it may still be worthwhile.
One final point. IBM, as did Telelogic before them, should be able to run a health check on your database which will yield the information required to produce the schema, along with other information showing where good practices have been bypassed. There is nothing magic about the tests that are run, but it is often more efficient to pay someone to carry out this type of one-off activity, rather than investing in creating scripts and designing tests that will not be used again.