Welcome to Telelogic Product Support
  Home Downloads Knowledgebase Case Tracking Licensing Help Telelogic Passport
Telelogic DOORS (steve huntington)
Decrease font size
Increase font size
Topic Title: Classic way of organizing requirements
Topic Summary:
Created On: 10-Mar-2007 04:44
Status: Post and Reply
Linear : Threading : Single : Branch
Search Topic Search Topic
Topic Tools Topic Tools
Quick Reply Quick Reply
Subscribe to this topic Subscribe to this topic
E-mail this topic to someone. E-mail this topic
Bookmark this topic Bookmark this topic
View similar topics View similar topics
View topic in raw text format. Print this topic.
 10-Mar-2007 04:44
User is offline View Users Profile Print this message


rajavel subramanian

Posts: 13
Joined: 6-Mar-2007

Hi,
It is recommended practice that we set an attribute against object to identify each of them as requirement or not. i.e., we set an attribute for object heading at non-requirement and leaf object text as requirement.  Just want to double check with others... is this the classical way of organizing requirements.

Report this to a Moderator Report this to a Moderator
 12-Mar-2007 08:39
User is offline View Users Profile Print this message


Tony Goodman

Posts: 1098
Joined: 12-Sep-2002

Yes, it is common practice to have an attribute, either a boolean "Is Requirement", or even an enumeration such as { Requirement, Supporting Information, etc ....} so that you can easily distinguish between requirements and the supporting structure of the document.

This also make metrics collection and analysis much easier.

Sticking to other rules, such as ensuring that all text objects are leaf objects, i.e. requirements don't have children, will also save trouble later.

-------------------------
Tony Goodman
http://www.smartdxl.com
Report this to a Moderator Report this to a Moderator
 12-Mar-2007 22:30
User is offline View Users Profile Print this message


Paul Miller

Posts: 376
Joined: 2-Oct-2002

Have never fully understood why all text objects must be leaf objects. I've seen it in the Telelogic DOORS training material but the reason why is not articulated. Can anyone articulate the inherent danger of doing this because I havn't experienced any fatal problems yet?

I find that nesting bullet lists so that the individual child bullet objects sit one level below their respective parent bullet object rather useful, particularly when managing links to either the parent or child buillets. This allows a trace script to determine if a link is going to either a child bullet object or the parent object of a bullet list and display the full requirement construct accordingly (bullet lists tend to fracture requirements into two parts, the parent and it's children). Also allows para numbering scripts to correctly number the child bullets.

-------------------------
Paul Miller
Specification Practices Specialist,
EuroCyber,
Melbourne, Australia.
Mobile: +61 (0)418 135 103
Web Site: http://www.eurocyber.biz
E-mail: miller@eurocyber.biz">pmiller@eurocyber.biz
Report this to a Moderator Report this to a Moderator
 12-Mar-2007 23:04
User is offline View Users Profile Print this message


Mary Schweizer

Posts: 20
Joined: 20-Dec-2002

Paul,

You are a long time DOORS user and if you haven't run into any problems yet with your method of nesting bullet lists, you probably won't ever.

But since you asked, the best description I could find of why all text objects should be leaf objects was in the DOORS built-in help manual. I've pasted it below.

"We recommend that each object is either a heading (its Object Text is blank) or normal text (its Object Heading is blank), but not both. This gives a cleaner and more manageable structure to your module. It also means that if you export from DOORS to other applications that don't have the concept of multi-attribute objects, you get what you expect.

For example, word processors don't let you combine heading and text in the same paragraph. If you don't combine heading and text in your DOORS objects, each object is exported as a separate paragraph, which is what you'd expect. If you combine heading and text in one object, when you export to a word processor, the object is exported as two paragraphs, one that contains the heading and another that contains the text."

Mary Schweizer

-------------------------
Mary Schweizer
BAE Systems
Report this to a Moderator Report this to a Moderator
 12-Mar-2007 23:20
User is offline View Users Profile Print this message


Paul Miller

Posts: 376
Joined: 2-Oct-2002

Hi Mary,

The extract you quoted from the DOORS manual is a warning about entering text into both the Object Heading and Object Text attributes. I agree with the warning about this problem.

The warning that I don't understand is to do with nesting an object that only has Object Text underneath another object that also only has Object Text.

-------------------------
Paul Miller
Specification Practices Specialist,
EuroCyber,
Melbourne, Australia.
Mobile: +61 (0)418 135 103
Web Site: http://www.eurocyber.biz
E-mail: miller@eurocyber.biz">pmiller@eurocyber.biz
Report this to a Moderator Report this to a Moderator
 13-Mar-2007 14:41
User is offline View Users Profile Print this message


Pekka Mäkinen

Posts: 276
Joined: 18-Mar-2004

Your bullet list example is a good example of how to use nested (parent - child) requirement objects. But generally there is a problem in such structures, if created by mistake by some user, as DOORS e.g. would delete the child requirement also when deleting the parent requirement.

-------------------------
Pekka.Makinen@softqa.fi
SoftQA Oy -http://www.softqa.fi/
Report this to a Moderator Report this to a Moderator
 14-Mar-2007 10:56
User is offline View Users Profile Print this message


Hazel Woodcock

Posts: 78
Joined: 6-May-2005

Paul,

The answer is not so much DOORS specific, more a general requirements management issue. If each requirement is complete, atomic, and all the other good things that a requirement should be then bullet points don't work, for instance;

The following items shall be included in the final product
- power cable
- interface cable
- instruction book

When you look at one of the bullet points you have 'power cable'. A better way of phrasing is to have three distinct requirements that can be individually tracked, verified and implemented.

From the DOORS perspective, if you want to see the whole requirement you have to look at two objects which adds complication.

I have a whole hobby horse on this one, so I shall stop there, but it is a discussion that frequently occurs.

Hazel
Report this to a Moderator Report this to a Moderator
 19-Mar-2007 18:50
User is offline View Users Profile Print this message


Alexander Almoian

Posts: 10
Joined: 13-Feb-2007

Hi Paul:

I am a firm believer of having Object Text (OT) children of OT.  If the spec states:
Under condition A the system shall :
1 do B

2 do C, etc

And 1 and 2 etc., are assigned to different subsystems and

1 and 2 are identified as requirements and parents to different lower spec reqts.

If 1 and 2 are not children of the condition, a trace report of lower spec will show parent req. as "do C", which is meaningless.

However, if they are children, the trace report (with ancestors selected) will have:
"Under condition A

do C"  which is much more useful.

fficeffice" />> >

I have produced a large formal module (15000 objects) with this structure with No problems.

Report this to a Moderator Report this to a Moderator
 19-Mar-2007 22:18
User is offline View Users Profile Print this message


Paul Miller

Posts: 376
Joined: 2-Oct-2002

Getting back to my original question based on Tony Goodmans answer to Rajavel's original query - does anyone know why Telelogic states the following during their DOORS training course "Don't make text objects children of other text objects" - with the "Don't" in red bolded letters. This sounds more like a explict warning than an optional recommendation.

The Telelogic trainers are not sure about this either other than a concern about the fact that deleting the parent object will delete the child objects. But this is true for heading objects as well, so why the big "Don't" in the training material? I'm just wondering if Telelogic has not accounted for nesting of text objects for bullet lists and should downplay the explicit "Don't" with a "Be aware". Unless of course there is some other nasty that I'm not aware of.

-------------------------
Paul Miller
Specification Practices Specialist,
EuroCyber,
Melbourne, Australia.
Mobile: +61 (0)418 135 103
Web Site: http://www.eurocyber.biz
E-mail: miller@eurocyber.biz">pmiller@eurocyber.biz
Report this to a Moderator Report this to a Moderator
 20-Mar-2007 08:37
User is offline View Users Profile Print this message


Andrew Tagg

Posts: 151
Joined: 26-Oct-2004

No nasties that I am aware of, and I have a LOT of nested structures such as Paul mentions. In fact we never use the heading field at all. All our data is in the object text field, with a 'paragraph style' attribute to denote if it is heading style or body text, bullet etc. These styles map to word styles when we export. We also use nesting as this makes for simpler reorganising of the structure using drag and drop. Andrew

-------------------------
Andrew Tagg
Thales Air Systems, Melbourne
Australia.
andrew.tagg@thalesatm.com
Report this to a Moderator Report this to a Moderator
 20-Mar-2007 09:09
User is offline View Users Profile Print this message


Tony Goodman

Posts: 1098
Joined: 12-Sep-2002

I don't think there is a right or wrong answer here. Decisions on how to use doors will depend on lots of factors such as who the users are (expert/naive), how you produce documents (word/html/archive).

My original concerns for not nesting text object are as follows:

1. Inexperienced users get confused by the hierarchy which is not immediatley apparant while editing if you nest text objects. Yes, you can see the hierarchy in the tree view - but many users don't look there.
Selecting multiple objects has "unexpected" results if the user does not fully understand the rules.

2. Traceability columns do not support nested requirements, so extra DXL is required to process links and target/source objects. Also, you need to keep child objects together, in the correct order for them to make sense. This causes pain if the tool support is not easliy to use and readily available.

3. Requirements should be atomic. Most RE books state this.

4. DOORS is a database, not a word processor. Positioning of objects in the hierarchy should not affect the meaning of a requirement. I would also add that the use of bold/italic to imply some meaning is also a very dodgy approach to requirements management.

5. If you nest text objects, understand how it works and have tool support etc, what happens when a user moves one requirement below another (possible unrelated requirement) accidentally? How do you spot this?

Rant over.
Like I say, there is no right or wrong answer, but I think I am less wrong that some :-)

-------------------------
Tony Goodman
http://www.smartdxl.com
Report this to a Moderator Report this to a Moderator
 20-Mar-2007 23:59
User is offline View Users Profile Print this message


Paul Miller

Posts: 376
Joined: 2-Oct-2002

Well answered Tony.

I guess it boils down to whatever works for the environment your working in.

W.r.t. traceability - we've developed a custom DXL layout trace script which looks for parent and child bullets and displays this info back to users so that they are aware and can see the other half of the requirement.

We also have a DXL layout paragraph number script which helps users to see how the individual objects are hierarchically nested - as you said, not all users make use of the Module Explorer, but the para number column seems to help here. We've built in some business rules into the script so that it will alert users about inappropriate nesting, duplicate para numbers due to hanging paragraphs etc.

-------------------------
Paul Miller
Specification Practices Specialist,
EuroCyber,
Melbourne, Australia.
Mobile: +61 (0)418 135 103
Web Site: http://www.eurocyber.biz
E-mail: miller@eurocyber.biz">pmiller@eurocyber.biz
Report this to a Moderator Report this to a Moderator
 2-Apr-2007 09:55
User is offline View Users Profile Print this message


Karen Kayam

Posts: 6
Joined: 28-Feb-2007

Most of the main reasons have already been mentioned... Here are some more...
 

In general, it is a "best practice".
I try to promote grouping requirements by topic or functionality (Heading object), and each requirement (Text object) with its own "The --- shall --- " format or variation of such. By keeping the requirements "independent", the statistics will be more accurate (filtering with Object Heading not empty), information via links can be easily manipulated...


- Dynamic Customization: In constantly broadening the scope of Doors process support, DXL together with object orientation and best practices provide the toolset for a dynamic and changing environment.


Example: Created a "report" module to display a filtered version of requirements from many modules in a project folder. When users requested to see the context of the selected requirements, it was very easy to pull out the objects in the tree reaching the requirements, not only in the form of object headings, but also with document section number (Object Number)


- Consistency and Readability: Each level of requirement documentation may be written by many people, and the next level of documentation (more detailed) is written by a different set of people who must easily interpret the level above. Separating the Heading objects from the Text objects allows all users to clearly understand the context of the documents.


- Change Management - A change should be applied to a requirement at a specific level, which should not include more than one object unless the referring to more than one requirement. In Alexander's comment from March 19th, what happens when the condition for doing B changes? How many objects should be modified for such a change? How would traceability display this change to documents at a different level? (In your case, I would also suggest creating a subsystem attribute and indicating the difference between the requirements with the attribute - which probably applies to many in your module).


To summarize: If using Doors to "document" requirements, then it doesn't matter what you do unless all who write at this document level use the same "standard". If using Doors to "manage" requirements and processes, it is sooo important to keep things as clear and object-oriented as possible (requirements, DXL scripts, process components...)


Karen Kayam
Product Development Analyst, PLA - MIS
NICE Systems. Israel
(M) +972 (54)5442193
Karen.Kayam@nice.com
www.nice.com

Edited: 2-Apr-2007 at 09:57 by Karen Kayam
Report this to a Moderator Report this to a Moderator
 2-Apr-2007 23:47
User is offline View Users Profile Print this message


Louie Landale

Posts: 2070
Joined: 12-Sep-2002

Having an attribute that distinquishes a requirement from non-requirements is highly desirable; as Goodman said as a Boolean or enumerated.

Setting that attribute value based on structural issues may be OK to get a jump start on the attr value, but is not otherwise desirable. For example you can (and should) certainly have non-required verbiage in a spec, as such text makes the spec easier to read. 'Definitions' certainly comes to mind, but also major headings should have a paragraph at the top that helps the reader understand what's in the section.

Even the age-old 'rule' that Required iff text contains 'Shall' is imperfect.

So yes have the attribute, but set it mindfully.

- Louie
Report this to a Moderator Report this to a Moderator
 2-Apr-2007 23:58
User is offline View Users Profile Print this message


Louie Landale

Posts: 2070
Joined: 12-Sep-2002

You'll find an issue in older organizations whose non-DOORS procedures still like to refer to a 'requirement' by its 'Paragraph Number'. Traditionally that would be the section number followed by the paragraph number therein, e.g. "3.2.2.1 #3". Nesting text objects will through that notion into disarray.
Report this to a Moderator Report this to a Moderator
 2-Apr-2007 23:58
User is offline View Users Profile Print this message


Louie Landale

Posts: 2070
Joined: 12-Sep-2002

This shows the classic conflict between the needs of the [1] Requirement Managers and the needs of the [2] Spec Readers. [2] likes bulleted lists and other managerial nightmares. [1] cannot realistically handle them since requirements should be clearly understood when taken OUT of context.

In this case we should either put the entire structure into a single DOORS object, or as you suggest make it 3 requirements, each saying "... shall be included in the final product". ..err.. I digress: "The contractor shall include Power Cables in the final Product". That decision 'should' be whether the 23 conditions will be tested and proved separately; in this case clearly 'yes' they will.

- Louie
Report this to a Moderator Report this to a Moderator
 3-Apr-2007 00:06
User is offline View Users Profile Print this message


Louie Landale

Posts: 2070
Joined: 12-Sep-2002

Great reasons. But I would like to point out something that you said is incorrect: DOORS is a word process and is NOT a database. There is no 'Object Oriented' anything in DOORS except in the name. You cannot make relations. You can barely make a hierarchy. Requirements exist on only one place instead of the normal multiple places. You cannot make a silk purse out of a sow's ear. The fact that its clearly "spec" centric causes so many problems that cannot be overcome by the clumsy 'linking' they have.



- Louie
Report this to a Moderator Report this to a Moderator
Statistics
20925 users are registered to the Telelogic DOORS forum.
There are currently 0 users logged in.
The most users ever online was 15 on 15-Jan-2009 at 16:36.
There are currently 0 guests browsing this forum, which makes a total of 0 users using this forum.
You have posted 0 messages to this forum. 0 overall.

FuseTalk Standard Edition v3.2 - © 1999-2009 FuseTalk Inc. All rights reserved.