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: Obect numbers - intended use?
Topic Summary:
Created On: 24-Nov-2006 14:31
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.
Answer This question was answered by Louie Landale, on Wednesday, December 20, 2006 1:19 PM

Answer:
Before we start, DOORS changed the meaning of 'number' and now its confusing. I'm going to refer to it as the 'paragraph number'.

A hierarchical spec has headings under headings. If a parent has paragraph number "3.2" then its child headings are "3.2.1", "3.2.2" etc. Obviously.

DOORS wants to preserve that and rightfully so. If there are such text objects under a heading followed by sub-headings, you want to preserve that above paragraphs numbering; but that begs the question, what paragraph number do you assign to non-Heading text objects that come before sub-heading objects? Also, how do you deal with non-Heading text objects that come after such heading objects?

In your examples, what numbers 'should' those non-Heading text objects have? The dash indicates non-Heading text objects. Your first set indicates that the two requirements are at level 4 (there are 4 sets of digits separated by 4-1=3 periods), and the zero indicates they come after the main level 3 heading. Your second set indicates again these again are level 4, and the last '1' indicates they come after the 5.2.2.1 heading.

If DOORS suppressed the "0" of those level 4 text objects, then the number would look like "5.2.2-1"; which is a number you'd get from a level 3 text object that comes after the level 3 heading 5.2.2.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

I believe, by policy, objects should have a hierarchy with these rules:
[1] Level 1 objects shall be Headings. Exception would be optional text objects at the very top of the module before the first level 1 heading (perhaps a title before paragraph "1. Scope".
[2] A Heading Object's parent shall be a Heading (not a Text).
[3] A Text object shall have no preceeding sibling that's a Heading. Stated another way: all the immediate child text objects of a parent shall come before all the immediate heading objects of that parent.

Notice that no rule prevents text objects from having subordinate text objects. You may want to do that when perhaps you say "shall be as the following list", and then have objects comprising the list.

Notice that rule [2] has the effect that a Text object can never be the ancestor of a Heading object.

The purpose of rule [3] is to insure that the spec reads correctly ..err.. I mean intuitively: When you see a text object you can tell what section its in by looking for the first heading object above it, just like you do when reading a paper spec.

The above rules prevents your 2nd examples that feature paragraph numbers that contain "1-" or "2-". It also means that no Heading object's paragraph number has a "0-" in it.

Had a script a long time ago that checked for all that stuff.

- Louie
 24-Nov-2006 14:31
User is offline View Users Profile Print this message


Jim Backus

Posts: 21
Joined: 27-Apr-2006

The way I've always used DOORS and assumed was the correct way is that objects after a heading have the next level, however when used in this way the object numbers have extra zeros. While correcting levels in a DOORS module I see that if objects after a heading have the same level as the preceeding heading the object numbers do not have the extra zero.

For example:

(Obj. Num.) 5.2.2 (Obj level) 3 (Object) A Heading
(Obj. Num.) 5.2.2.0-1 (Obj level) 4 (Object) Requirement text
(Obj. Num.) 5.2.2.0-2 (Obj level) 4 (Object) Requirement text

But:

(Obj. Num.) 5.2.2.1 (Obj level) 4 (Object) A Heading
(Obj. Num.) 5.2.2.1-1 (Obj level) 4 (Object) Requirement text
(Obj. Num.) 5.2.2.1-2 (Obj level) 4 (Object) Requirement text

DOORS help gives no advice on the subject, or explanation of the spurious zeros. My question: Presumably the first example is correct usage and the extra zeros should be ignored as a quirk of DOORS? The advantage of having requirements one level down from the associated heading is that if a new heading is added at the same level as the first (e.g. 5.2.3 in the first example above), it is automatically placed after the block of level 4 (and lower) objects.

Comments and advice please?

-------------------------
Jim Backus<BR>Ultra Electronics, Controls
Report this to a Moderator Report this to a Moderator
 27-Nov-2006 14:34
User is offline View Users Profile Print this message


Hazel Woodcock

Posts: 78
Joined: 6-May-2005

The object numbers for text objects are not really intended for use by the user. They are a structural device for DOORS to know where the objects sit in the hierarchy.
Text object should (best practice) be placed hierarchically below the heading that they 'belong' to. Multiple advantages in terms of filtering (ancestors and descendants), restructuring (move a whole section by moving the heading) and others.
It is best to use the module explorer to keep an eye on the structure and not get hung up about the object numbers for anything other than headings.

Hazel
Report this to a Moderator Report this to a Moderator
 29-Nov-2006 21:08
User is offline View Users Profile Print this message


Louie Landale

Posts: 2070
Joined: 12-Sep-2002

Answer Answer
Before we start, DOORS changed the meaning of 'number' and now its confusing. I'm going to refer to it as the 'paragraph number'.

A hierarchical spec has headings under headings. If a parent has paragraph number "3.2" then its child headings are "3.2.1", "3.2.2" etc. Obviously.

DOORS wants to preserve that and rightfully so. If there are such text objects under a heading followed by sub-headings, you want to preserve that above paragraphs numbering; but that begs the question, what paragraph number do you assign to non-Heading text objects that come before sub-heading objects? Also, how do you deal with non-Heading text objects that come after such heading objects?

In your examples, what numbers 'should' those non-Heading text objects have? The dash indicates non-Heading text objects. Your first set indicates that the two requirements are at level 4 (there are 4 sets of digits separated by 4-1=3 periods), and the zero indicates they come after the main level 3 heading. Your second set indicates again these again are level 4, and the last '1' indicates they come after the 5.2.2.1 heading.

If DOORS suppressed the "0" of those level 4 text objects, then the number would look like "5.2.2-1"; which is a number you'd get from a level 3 text object that comes after the level 3 heading 5.2.2.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

I believe, by policy, objects should have a hierarchy with these rules:
[1] Level 1 objects shall be Headings. Exception would be optional text objects at the very top of the module before the first level 1 heading (perhaps a title before paragraph "1. Scope".
[2] A Heading Object's parent shall be a Heading (not a Text).
[3] A Text object shall have no preceeding sibling that's a Heading. Stated another way: all the immediate child text objects of a parent shall come before all the immediate heading objects of that parent.

Notice that no rule prevents text objects from having subordinate text objects. You may want to do that when perhaps you say "shall be as the following list", and then have objects comprising the list.

Notice that rule [2] has the effect that a Text object can never be the ancestor of a Heading object.

The purpose of rule [3] is to insure that the spec reads correctly ..err.. I mean intuitively: When you see a text object you can tell what section its in by looking for the first heading object above it, just like you do when reading a paper spec.

The above rules prevents your 2nd examples that feature paragraph numbers that contain "1-" or "2-". It also means that no Heading object's paragraph number has a "0-" in it.

Had a script a long time ago that checked for all that stuff.

- Louie
Report this to a Moderator Report this to a Moderator
 30-Nov-2006 09:31
User is offline View Users Profile Print this message


Hazel Woodcock

Posts: 78
Joined: 6-May-2005

hmmm....

I have to take issue with one of your points Louie, you have found a hobby horse of mine.

you say 'no rule prevents text objects from having subordinate text objects'.

Best practice says you shouldn't.
The two guidelines from the DOORS training coure are
1 Make text objects children of the heading object they are associated with
2 Don't make text object children of other text objects

If you have "shall be as the following list" structures then each of the items on the list is not going to be a full requirement. When you view the object text from the other end of a link you get a word or two instead of something that is truly meaningful. It is better to restate a few words at the start of several requirements to make each a whole requirement that can be assessed individually. If the whole list is needed to make sense of the 'thing' then it should be stated as a single requirement (single DOORS Object).

<dismount from hobby horse>
:-)

Hazel
Report this to a Moderator Report this to a Moderator
 1-Dec-2006 20:03
User is offline View Users Profile Print this message


Louie Landale

Posts: 2070
Joined: 12-Sep-2002

We are struggling with that construct ourselves. But we are dealing with folks who only care about the 'spec' as they see in in MS-Word, where the 'as follows' construct is customary and correct. They want specs imported, then exported, to look very much like the original. Yes, for the 'database' we should get rid of the 'as follows' and just restate the criteria for each case. But then of course you have the problem when dealing with an ordered list; such as "when X occurs the system shall do these things in this order: a b c". Maybe that's 4 requirements, [1] shall do a [2] shall do b [3] shall do c [4] shall be in the order a,b,c.

However, that has nothing to do with the rule about text objects having text object parents. After all, all table cells are 'text objects' and they all have 'text object' parents in the Row Cells, and in the Table Cell. And DOORS routinely inserts tables 'below' rather than 'after' the current object. Try printing the "number" of a table cell object. And one main reason to nest Text objects is so that if you move or delete one you are forced to move or delete the others, and that's a good way to force a group of object (requirements) that are intended to be grouped together.

Maybe someday we can get folks thinking "db" first and "spec" second.

- 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.