Topic
  • 9 replies
  • Latest Post - ‏2013-02-01T19:13:24Z by JWiseman
SystemAdmin
SystemAdmin
1084 Posts

Pinned topic Managing DOORS Table objects

‏2013-01-31T03:30:38Z |
Hi,
I'm a systems engineer, not a software engineer. And, I'm struggling with the best way to manage requirements when they are presented in tables. I've discussed the issue with others more experienced with DOORS (including those who create DXLs) and reviewed some of the threads in this forum. The answer seems to keep coming back as "stay away from DOORS tables." I'm finding it hard to believe that this mature a software tool, which was specifically developed to manage requirements, doesn't have the capacity to manage requirements when presented in the form of a table. I thought I would present the issue here and see if a DOORS expert can clear up why this is such an issue.

Basically, most of the posts I've read have been about how to present the tables. I am concerned about managing the contents of the tables (i.e., the requirements)--from development through verification. Each requirement should be able to stand alone (referred to as modularity) such that if that requirement is separated from the spec, it can still be understood and handled. We take each requirement and dissect it to lower level specifications (i.e., modules). We take each requirement and assign it to a specialist. We take each requirement and define how that requirement is verified, we often verify it separately, and sell it off (i.e, customer review and approval) separately. It seems that using tables embedded within a DOORS object is the wrong approach because we aren't treating the cell contents as separate objects to be managed. But, everyone tells me that putting different requirements in a DOORS constructed table is a problem because the attributes (which are the key way in which we manager the requirements) are not shown in the View and therefore, cannot be exported along with other requirements in the module.

Below is a simple example requirement that should be presented in a table. How do I construct a DOORS table that has some cell contents identified as requirements and be treated just like the other requirements when extracted into a verification matrix for example. A verification matrix has the requirement id (DOORS generated attribute), the requirement title (custom attribute), the requirement text (defined attribute), and then other custom attributes (e.g. verification level/method/type) in a row. Every requirement for that specification(i.e., module) should be listed in the verification matrix.

Example Requirement Statement: "Product A shall possess the characteristics shown in Table 1."
Table 1 has two columns. The first row is the column titles. The Col A cells contain the name of each characteristic. The Col B cells contain the requirement value. The Col B table objects (i.e., cells) could be defined the object type "Value" to identify that they are the actual requirement value. Ideally, when extracting the requirement as a singular object to manage, I would want to be able to construct a shall statement that becomes a template for the requirements presented in the table. For example, "Product A shall possess a ColA equal to ColB." Each requirement from Rows 2 and up could be separated and assessed individually as:
1. Product A shall possess a volume equal to XX in3.
2. Product A shall possess a mounting I/F area equal to XX in2.
3. Product A shall possess a wall thickness equal to XX mils

But, in the exported MS Word spec and in the standard DOORS module view, I would want the requirements presented in the table format. I want the metrics requirement count for the spec to be the number of individual object records (i.e., shall statements) with object type "Requirement" plus the number of individual table cell object records with object type "Value."

Sorry about the long post. I don't know any other way to explain it. I also attached a file with the example. How do I construct the table so that I can manage the full set of real requirements and then how do I execute those extractions or scripts. I don't want to default back to embedding a table as an object and I don't want to write out multiple, individual shall statements because the tables I need are actually pretty huge. Anyone got any good ideas?
Updated on 2013-02-01T19:13:24Z at 2013-02-01T19:13:24Z by JWiseman
  • JWiseman
    JWiseman
    23 Posts

    Re: Managing DOORS Table objects

    ‏2013-01-31T04:55:39Z  
    There are a couple of issues that you seem to be dealing with here:

    1) At first glance, none of these appear to be actual requirements. They are design specifications. For example, a design with a black surface coating has to exist because of what requirement or system constraint? The interface area might be based on a thermal conduction requirement or a mandate to be attached to another specific device. The given area spec is the designed compliance to the unspecific requirement.

    However:

    2) Regardless of #1 above, DOORS is good for design specifications as well, so your initial question of how to handle the table still applies. The following are my thoughts:

    2a) I agree completely with the other things that you've heard about NOT putting requirements into tables. Note that you CAN put requirement DETAILS into tables (more on this later). All requirements in a spec have multiple attributes associated with them and all of DOORS views and reports are designed to work on normal paragraph type requirements. I Guarantee that if you put formal requirements into tables you'll constantly be fighting with them.

    2b) For your example using the table 3.3-x Product A Characteristics, the sentence preceding ("Product A shall possess the following characteristics") is the actual requirement and should have a requirement ID tag on it. In DOORS, the table objects should be nested below the level of the requirement. In a requirements view, the details can be seen by simply turning off the filter or, you could set up a view that shows all requirements AND THEIR DESCENDANTS. You would need to provide a better actual requirement statement though (e.g., "Product A shall be constructed based on the mechanical form factors as given in Table 3.3-x", etc.).

    Note that when you get down to lower level design specs, many times that table you have will be replaced with a formal drawing so the spec might have a single item stating something like "Product A shall be constructed based on all of the specifications given in drawing XYZ". As you can see, the problem you are having with the table is the same as what you'll have when you start creating drawings of mechanical and architectural structures.

    2c) The few times I've seen where we were forced to use a table for requirements for presentation purposes, each requirement existed on its own row. Your example does this as well (assuming that you needed traceability). If you need to do this, I personally would toss the table and replace it with multiple requirements (one requirement statement for each row) and group them in the same section or subsection of the document (see 2d below). This solves your issue about the expanded text for rows. If you need the expanded text, just enter it that way and don't use any table.

    2d) Cohesion is a top priority to allow for spec organization and is the area that many folks building specifications fall down on. From your example, does the reason (i.e., the requirement) that the surface coating be black have ANYTHING AT ALL to do with the Amperage tolerance? No? Well then they certainly don't belong in the same table or requirement grouping. The table in your example is what I can a "junk drawer" or miscellaneous requirement. They exist because a more cohesive grouping based on what each is about has not been introduced. You will find that when requirements are grouped cohesively, the tables that you end up with will usually only need a single sentence requirement that references the table.

    Anyway, hope this gives you some ideas!
  • SystemAdmin
    SystemAdmin
    1084 Posts

    Re: Managing DOORS Table objects

    ‏2013-01-31T23:39:58Z  
    There are two issues here to consider.

    1. The use of tables in specifications regardless of the tool being used

    2. The usability of tables in DOORS

    Tables are useful in specs but they can pose problems.

    Tables concentrate a lot of requirements in a 2 dimensional structure. Is the table one requirement or many requirements? How many requirements are in there? How do you represent each cell of a table in a Requirements Traceability Matrix (RTM)?

    The cell structure of a table often fragments the requirements into criteria pieces. This is prone to some pieces being overlooked or incorrectly constructed by the reader (particularly in big tables).

    Each cell containing a requirement requires a UID so that the cell can be uniquely referenced for traceability. Trying to display these UID’s in table cells can get messy.

    The larger that tables get, the harder they become to manage and to interpret.

    So the recommended practice is only use tables if they offer a means for improving understanding and reducing ambiguity. Keep them small or break a larger table up into smaller cohesive table chunks if possible.

    As for using tables in DOORS. It's mostly an issue of usability and maintainability. The formatting and management features for tables in DOORS are very primitive and very time consuming. You can't cut and paste rows and columns, changing column widths is painful as it has to be done via a dialogue box instead of grab and drag with the mouse, merging of cells has to be done manually via fiddling around with column widths, forget about using rotated text and shading and other rich formatting options - and so on. If DOORS had similar features as MS Word for managing tables, that would be nice.

    Each cell in a DOORS table is exactly the same as any other module object, except that you cannot display the attributes of a DOORS table cell in the columns of a DOORS view. You can select which object attribute you would like to see displayed in the table cells, but only one at a time and it applies to the whole table. Some get around this by creating a single DXL Attribute that concatenates multiple attribute values together and selecting this DXL attribute as the attribute to display - but this can get messy. The problem with representing table cells in RTMs still applies.

    Tables can't be avoided, so keeping them small and their formatting as simple as possible should be the aim.
    Paul Miller,
    Melbourne, Australia
  • DOORSWizard
    DOORSWizard
    37 Posts

    Re: Managing DOORS Table objects

    ‏2013-02-01T12:31:24Z  
    Based on my experience, I completely concur with both of the previous responses and would recommend staying away from DOORS tables (or OLEs) for that matter in your situation. I think you are looking at separating each requirement into it's own object, I certainly like the suggestion of grouping the similar requirements into their own section (or subsection). To truly gain the value of DOORS for everything it has to offer (Traceability Views, Verification Matrix, etc...) you should have each requirement in it's own object (where each object is not a table cell). With this approach what you will find however is that you can very easily still end up with your RVM and/or traceability view exported out as a table into Word or some other format of your choice.
  • llandale
    llandale
    637 Posts

    Re: Managing DOORS Table objects

    ‏2013-02-01T16:01:42Z  
    "Requirements Management" insists that each requirement is identifiable; testable; unary; unambiguous, bla bla bla, most also includes "clear" which means it is understandable when read by itself. Thus, "45" is not a requirement even when it is a cell in a table that is required.

    So a table (and bulleted lists) make for poor "requirements". You can indeed ground the table/list as a requirement with a statement "shall be as the following list" or "as per Table-4"; in which case THAT statement is the requirement and the table/list is supplemental information. Using this approach, there is no need to drastically complicate things by trying to assign individual attribute values to individual table cells; in which case the table reasonably displays the needed information. And if each cell doesn't have attr values then the entire table can be in a single DOORS object; IMO best displayed as some kind of Word/Excel OLE table.
  • JWiseman
    JWiseman
    23 Posts

    Re: Managing DOORS Table objects

    ‏2013-02-01T18:28:56Z  
    • llandale
    • ‏2013-02-01T16:01:42Z
    "Requirements Management" insists that each requirement is identifiable; testable; unary; unambiguous, bla bla bla, most also includes "clear" which means it is understandable when read by itself. Thus, "45" is not a requirement even when it is a cell in a table that is required.

    So a table (and bulleted lists) make for poor "requirements". You can indeed ground the table/list as a requirement with a statement "shall be as the following list" or "as per Table-4"; in which case THAT statement is the requirement and the table/list is supplemental information. Using this approach, there is no need to drastically complicate things by trying to assign individual attribute values to individual table cells; in which case the table reasonably displays the needed information. And if each cell doesn't have attr values then the entire table can be in a single DOORS object; IMO best displayed as some kind of Word/Excel OLE table.
    I would like to add that there are times when it is necessary to provide table grounded to a single requirement where the table is fairly large. One example may be a non-linear performance profile that a Device must comply to. A table of highs, lows, and values of the functional variable the performance is based on would be an example of this.

    if this is the case, you really wouldn't want an OLE type table as it would not export into another form such as Word. In this case, the DOORS table works well because during export it will automatically split across pages. An OLE table that is longer than the page will either not export or can result in other text being lost in the export as well.

    Again though, the table is not the requirement, it is simply a detailed reference that a single requirement needs.
  • SystemAdmin
    SystemAdmin
    1084 Posts

    Re: Managing DOORS Table objects

    ‏2013-02-01T18:40:37Z  
    • JWiseman
    • ‏2013-02-01T18:28:56Z
    I would like to add that there are times when it is necessary to provide table grounded to a single requirement where the table is fairly large. One example may be a non-linear performance profile that a Device must comply to. A table of highs, lows, and values of the functional variable the performance is based on would be an example of this.

    if this is the case, you really wouldn't want an OLE type table as it would not export into another form such as Word. In this case, the DOORS table works well because during export it will automatically split across pages. An OLE table that is longer than the page will either not export or can result in other text being lost in the export as well.

    Again though, the table is not the requirement, it is simply a detailed reference that a single requirement needs.
    For this sort of very large reference table, my preference is to use a separate DOORS module, with attributes.
    Sometimes it works to put the table data in the main requirements module, using attributes, and with a view set up to show the relevant detail.
    OLEs are limited to a single page and become unweildy before that limit.

    DOORS tables are rarely the right thing to use. I am in agreement with Louie.
  • firstgentrekkie
    firstgentrekkie
    21 Posts

    Re: Managing DOORS Table objects

    ‏2013-02-01T18:50:22Z  
    • JWiseman
    • ‏2013-02-01T18:28:56Z
    I would like to add that there are times when it is necessary to provide table grounded to a single requirement where the table is fairly large. One example may be a non-linear performance profile that a Device must comply to. A table of highs, lows, and values of the functional variable the performance is based on would be an example of this.

    if this is the case, you really wouldn't want an OLE type table as it would not export into another form such as Word. In this case, the DOORS table works well because during export it will automatically split across pages. An OLE table that is longer than the page will either not export or can result in other text being lost in the export as well.

    Again though, the table is not the requirement, it is simply a detailed reference that a single requirement needs.
    Having had to spend endless hours grappling with OLE type tables, imported from Word and Excel, that were too long, too wide, or both, to publish, I heartily agree that a DOORS table can often be used without identifying each cell as a requirement. What we generally do is set the object type of each cell of the DOORS table to Information, and tie the table to the actual requirement using words like those suggested above: "...as shown in the table titled 'Test Messages' below..." in the Requirement object.
  • JWiseman
    JWiseman
    23 Posts

    Re: Managing DOORS Table objects

    ‏2013-02-01T19:00:39Z  
    For this sort of very large reference table, my preference is to use a separate DOORS module, with attributes.
    Sometimes it works to put the table data in the main requirements module, using attributes, and with a view set up to show the relevant detail.
    OLEs are limited to a single page and become unweildy before that limit.

    DOORS tables are rarely the right thing to use. I am in agreement with Louie.
    I understand what you are saying. We have found though that there are times that you don't have a choice. In Government contracting where you are subcontracted to provide system requirements for the military, frequently they will provide you with the data constraints and they expect to see those tables with THEIR data in the main deliverable. This data, because it is needed to directly support the system requirements, must be in the same module. The customer expects you to occasionally export formally released versions of that module and send it to them so that they can place it into their own DOORS database. Defining a custom schema where they have to develop tools to piece the parts back together for reporting purposes isn't acceptable.

    Because there are usually many tables at this level of requirements (Systems of Systems), using attributes in the module is also unacceptable as they clog up all other attribute maintenance for the regular requirements. You also cannot see the "tabled" data in a normal export view of the main column text. With many of these constraints, the DOOORS table format is the only solution (unless you want to do months of DXL development which will only break the next time IBM updates DOORS).
  • JWiseman
    JWiseman
    23 Posts

    Re: Managing DOORS Table objects

    ‏2013-02-01T19:13:24Z  
    Having had to spend endless hours grappling with OLE type tables, imported from Word and Excel, that were too long, too wide, or both, to publish, I heartily agree that a DOORS table can often be used without identifying each cell as a requirement. What we generally do is set the object type of each cell of the DOORS table to Information, and tie the table to the actual requirement using words like those suggested above: "...as shown in the table titled 'Test Messages' below..." in the Requirement object.
    Exactly. And getting back to a point I made earlier, in general, tables in requirement specs should only be used to group cohesively related data together. If this is done, then the actual requirement is only about the one issue that cohesively groups the items in the table. An item should not be in a table simply because that was a convenient place to put it.

    Note that for ease of reading, tables may be used as a summary point for groups of items in the spec, in which case the cohesion is for the groups of items being summarized. The issue is the same though since the items being summarized are already spec'ed elsewhere.