DOORS Is Not Access — Part II

In my last entry I explained the concept of a public database. DOORS is a public database. Access is semi-public, as an Access developer can take steps to expose or hide the database from the users, where Oracle is usually intended to completely backend all data. Users don’t really go into an Oracle database and poke around.

This isn’t true for DOORS. When DOORS is used as anything other than a repository, users can usually see more than they absolutely need to. This makes DOORS different from other databases.

Let me illustrate my point with a story.

 A manager for a test group found out DOORS could run DXL. He didn’t really know what DOORS was other than a database tool for requirements. He hired a developer, who had originally had an Oracle background, to work for him to create a custom tool using DXL, for testers to enter data. Once the data was entered, documents could be generated.

When I say custom tool, I mean custom. The developer worked on this tool for over a year. She had begun work on this tool before I was the DOORS Admin for the project she was on.

This developer didn’t know DOORS. She didn’t know DXL, but she read the DXL reference manual and taught herself. There is a difference between knowing DOORS and knowing DXL, and this developer knew DXL pretty well. But she didn’t always understand DOORS.

In doing some database work I discovered her tool and had to have her tool conform to some company standards. We needed a different way for the users to start the tool.

The developer used this as an opportunity to request enhancements. She requested that the data modules that her application relied upon be hidden from users. I told her that couldn’t be done. That if a user can update data in a module, then they can see the module, and there is nothing that could stop them from going into the module and just editing the data directly.

Remember, she’s over a year in development of this tool at this point. This is such a basic requirement, and there’s nothing I can do to stop a user from bypassing her tool altogether without some serious customization…you’re talking using triggers and doing some other things that could break existing functionality in the tool! Further, my guess is that she always wanted this capability and used the company standards change as a reason to ask me about it, because she couldn’t figure it out herself, and it’s such a basic function that it should be possible, right?

One year in, and she still had the mindset that DOORS is a database front-end.

You can put a front end on DOORS. You can wrap it in a DXL GUI and give it extra functionality, but you can never, ever forget that the users can see the modules that they can update. If users need to update “hidden” modules, well, you must always assume that the users will figure out where those “hidden” modules are.

A few weeks ago Fox News exposed their image directory on their Web server. How long did it take people to figure out that this was the case? And once people did, they started browsing around and sharing the information.

DOORS modules are public. People are naturally curious. Like Fox News found out, when you put something out there people will look. And in DOORS, we usually want people to look.

In a good DOORS schema, you need to assume that even though Sally works in Marketing and Harry is an engineer, that Harry is probably going to want to see Sally’s work from time to time, and vice-versa. What are some simple guidelines so that Harry doesn’t have to waste time finding Sally’s work?

  1. Folders should be named in a way that accurately describes their contents.
  2. Modules should be named accurately, independent of path. If there is a folder called “SSDD”, don’t put a module in it called “Wireless Communication”, as there may be a different folder somewhere else for “Wireless Communication”. Call it “Wireless Communication SSDD” or “SSDD – Wireless Communication,” and then name the module something just as descriptive
  3. If an abbreviation is used in a module name, that abbreviation should be spelled out in the module description whenever possible.
  4. View naming conventions are vital, otherwise any defined views across your modules will be hard to navigate. This is tough, because users can name a view anything they want. (I’ll mention a great way to deal with this in an forthcoming blog entry, so stay tuned!)
  5. Use as few link modules as possible to get the job done intuitively. This is subjective. I’ve worked on projects that only needed one link module per folder. And I’ve worked on others that needed many link modules in different locations. You don’t want your users to worry about link modules often, but if they ever have to, the link modules need to be very descriptive. If you can, just use one link module and do trace reports to/from individual formal modules. Again, different projects have different needs, so think about how to set up link modules carefully before you do. In my opinion, DOORS focuses things way too much on link modules. You can always filter the modules you want via the Analysis Wizard. Don’t focus on link modules. (My rule of thumb–one link module per folder, handling outgoing links for formal modules within the same folder. That way, there is never any guessing on which link modules contain which linksets.)

    As an aside, this same project, before I signed onboard, used just 1 link module for all links! Again, this mindset of DOORS being like Access was to the potential detriment of the company. Obviously we only need one “table” for link relationships, right? Forget about what the performance of the database will be like when we have thousands of links.

  6. Think ahead. Try not to put things in your database because of a deadline. This is the hardest thing about keeping a schema intuitive. There’s always some reason to bypass process and just do it now. If you do have to bypass process right now, ensure you come back to it later and make changes as soon as possible, and be sure to complain to management that they are ruining the ease of use for users of the database by not allowing time for planning.
  7. If anyone ever asks you where a module is found, that module or its encompassing folder structure is not intuitive and you really should consider changing its name, description, or location.
  8. Make sure attribute names and values cannot be misread. If you have a Requirement Type attribute, and one of the enumerations is “Business Rule” and another is “Functional Requirement”, will your users know the difference between the two?
  9. Getting it right the first time is vital if integrations (whether Telelogic or custom) are used. DocExpress and other programs that rely on DOORS schema information will just break on a module name/location change.

All of this sounds really simple and basic, but how many Access databases have you seen with tables and queries that were vital, but non-sensically or abstractly named? (My answer to this question is: “A LOT!”) The developer of that database knew his naming convention (assuming there was a naming convention), but it may not be obvious to you today. And the developer may have thought that no one else would ever need to know what that table or query is used for and why it’s there.

And unlike Access, DOORS gives you folders as a means of organizing your schema! Take advantage of this, and don’t take it for granted. Remember, DOORS is not an IDE. Nor is it an application for building databases and tables. It is an application for managing requirements, first and foremost.

In DOORS, you can never assume that a module is just for you, or just for a group. Every module that gets created will be seen by someone else eventually, and you will be asked about it if you’re still around. Keep these assumptions in mind, and your database will be easy to navigate, intuitive to all of your users, and much easier for you and all those who come after you to manage.

To summarize, in DOORS, the database front-end is the database back-end! Be as detailed as possible when naming everything and establish as many rules to keep things clean as possible. Further, making sure your users don’t create modules and attributes allows you to keep the database clean. Finally, make sure that every single module that exists has a reason for existing. Develop as much criteria for what goes into DOORS, naming conventions, and other standards as possible, and STICK TO THEM.

Keeping things tidy now will stop you and others from having to clean up major messes later.

7 Comments

  1. Thank you for the kind words.

    I just wanted to comment to let everyone know that I edited the above post today. I added an extra paragraph to item 5.

    It is dawning on me that outsiders to DOORS may think that a post like this is all over the place and not really “tight” and “focused”. But once you’ve been administering the tool for a few years you do realize everything to watch out for, and as the above post shows, that is quite a bit.

    To any DOORS newbies out there, don’t be discouraged or intimidated by the above. There’s just a lot of different things to look out for and I’m trying to be as clear as possible.

  2. In looking at a SQL type structure, naming follows object oriented or hierarchy rules: EMPLOYEE (table), DEPARTMENT (table), WORKS-IN (table expressing relationship), WORKS-FOR (another relationship).

    Is there a similar “rule” in DOORS? As in: SYSTEM-REQ(folder) contains SUB-A-REQ (module), SUB-B-REQ (module), and SOFTWARE-REQ (folder) contains SUB-A-SW-REQ (module), SUB-B-SW-REQ (module). Bi directional links are attributes from SYSTEM folder’s modules to/from SOFTWARE-REQ folder’s module.

    The above structure (and naming) can carry a project from SYSTEM level stuff all the way through TEST stuff, with necessary linking all the way, so it looks good to me.

    Also, in DOORS, I see the primary goal of linking is to establish the relationships: “is-satisfied-by” and “satisfies” – traceability.

    What say you, Kevin?

    Mike

    PS. Your website is terrific.

  3. Mike,

    Thank you so much for the kind words.

    This kind of question is EXACTLY the kind of question that someone who understands databases would ask, and then find out the differences in DOORS. This is exactly what I mean by “DOORS Is Not Access!”

    In your example, there is a list of employees in a table. And then there’s another list of departments in a table. An employee is assigned to a department. And then you could, in either table, create a relationship via a field that points to another. So EMPLOYEE Paul works in DEPARTMENT Accounting.

    We’re with each other so far I take it.

    DOORS can work this way. Sure. I could create a module called “DEPARTMENTS” and another called “EMPLOYEES” and create links between the tables, er, modules.

    The thing is, if you set DOORS up like this, you are killing your database.

    DOORS is Object-Oriented and not relational. All the links do is make a relationship between objects, but really one object doesn’t truly “know” about the other.

    In DOORS, the best way to approach putting a list of employees and departments in the database would be to put them into ONE Module, that had attributes for both employees and departments.

    Sounds like horrible database design? It’s not in the realm of DOORS. DOORS modules are not database tables, and thinking of them in that way is going to make for one very inefficient database.

    The reason for this is that if you just have a DOORS module containing employees, you can’t get any department information for those employees unless you also open the department module. This is inefficient for the user, who just wants to look at employees and departments.

    So it is a DOORS administrator’s job to ensure that in any module containing an employee, there is an up-to-date enumerated list of departments. This is efficient for the user, but inefficient for the DOORS Administrator. That’s ok. That is our burden, and it’s really why DOORS Admins should learn all the DXL they can.

    The answer to your question about links is essentially yes as far as the structure is concerned. You’ve made a comment in another thread and given me a great idea for a blog entry about links and link modules. I’ll discuss this more in-depth sometime soon.

Leave a Reply