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?
- Folders should be named in a way that accurately describes their contents.
- 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
- If an abbreviation is used in a module name, that abbreviation should be spelled out in the module description whenever possible.
- 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!)
- 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.
- 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.
- 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.
- 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?
- 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.