How to capture user clicking drop-down menu?

[DMT]

In the books I've read about writing use cases, there seem to be several themes:

1. Keep your use cases generally disconnected from the UI, including only the UI-related information that's pertinent to making the reader understand the use case. I.e., "User selects a transaction type, then clicks a button to continue," as opposed to something like, "User selects a transaction type from the combo box labeled 'Transaction Type.' User then clicks on the OK button or presses ENTER on the keyboard to trigger the OK button."
2. A use case should not "know" how it was initiated.
3. Use cases should be atomic, but not so small that you can explain what happens in just one short sentence.

Now, I'm confused a little bit about exactly how to write use cases to capture something along the lines of the following theoretical example:

- There is a menu item under the File menu called "Open Company Database." If the user triggers this option, the system displays a dialog, allowing the user to select a company database.
- There is an "open document"-looking button on the toolbar that triggers the same action. It looks like a blank page, just like the New Document toolbar button in MS Word.
- The File menu lists the 4 most recently used (MRU) company databases. If the user triggers one of these options, it just opens the company database.

Now, what I want to capture are the use cases that describe the behavior. I think the right way to document the actual use cases that happen once the menu item is clicked are the following:

- Open Company from Dialog - Describes opening a company from the dialog. Doesn't know how it was triggered, simply starts with "System displays the Open Company Dialog..." Includes the Open Company use case to actually perform the operations to open the company.
- Open Company - Describes the process of accessing the database to get the company information and displaying the information on-screen. Again, doesn't know how it was triggered. Starts with something like "System retrieves the information for the specified company, then displays the Main Information screen for the company database."

My question is, if these use cases aren't supposed to "know" how they got triggered, what use cases do I write to "fire" these use cases?  I could write something like, "Click File | Open Company Database Menu Option," but that seems too "small" for a use case.

An alternative I thought of is writing a "Click Menu Option or Toolbar Button" use case, which describes each option available to the user on both the toolbar and the menu, and describes each use case that gets invoked.  This would sort of be a "switch statement" use case.

Anyone have any words of wisdom here? I'm trying to go by the "Capture ALL functionality of your system through use cases" idea and for some reason I'm just struggling with this particular issue.

[Tjerk]

Hi DMT,

One way might be to specify the trigger as "the user selects the Open Company Database", not stating how that can be done (later in User Manual).

Including details of how is not a requirement (unless the stakeholders really require this). Your solution might e.g. not only be the menu, but also a shortcut key or a button. The user probably doesn't matter how he can trigger the use case. This means that even mentioning a dialog poping up is pointing to the how instead of what: the information shown to the user (e.g. The system enables the user to select which database to open).

So the things with the menu belong to design descriptions and lateron the user manual. Use Cases are not(!) meant to be a user manual.

Greetings,
Tjerk

[DMT]

Well, here's my golden rule:

I must be able to hand the design documentation over to a team of competent Windows programmers, lock them in a room, and in 12 to 18 months open the door and have a product that works exactly how I want it to work.

In my experience (writing 750 pages of requirements for the first 50% of our product), the following is what would be required in a "text-based" requirements document. I just need to figure out where it should go in a UML-centric design document!

1. There shall be a file menu at the top of the screen.
2. If the user presses ALT-F, the file menu shall drop down
3. There shall be one option in the File menu, labeled "Open Company Database."
4. If the user presses the letter O when the File menu is dropped down, the Open Company Database menu item shall be triggered.
5. If the user triggers the Open Company Database menu item, the system shall initiate the Open Company Database Using Dialog use case.
6. If the user presses CTRL-O on the keyboard, even if the File menu is not dropped down, the Open Company Database menu item shall be triggered.
7. There shall be a toolbar displayed at the top of the screen, directly under the menu bar.
8. The toolbar shall have one button with a 16x16 icon. (See attached BMP file for the icon.)
9. There shall be a tooltip for the menu item that displays the text, "Open Company Database".
10. If the user triggers the toolbar button, the Open Company Database Using Dialog use case shall be initiated.

This is all information that would go into the user manual in one form or another. And, this is critical information required to build and test the product.

So, my question is, basically, where does this go?  I THINK it makes sense to place this information in the following:

1. Description about the menu and toolbar placement, appearance, etc. goes into the UI specs. In EA this would go into the responsibilities for the main application window, or perhaps into "menu" and "toolbar" objects that are aggregated into the main application windows. This seems to make sense this this is stuff that's purely UI-centric--it has to deal with visual appearance.
2. Description about the fact that a use case gets triggered would go in one of two places:
 a) A "Trigger Menu Item or Toolbar Button" use case, as described in my original post. This seems to hold true to the tenet, "In a use-case driven approach, the set of use cases shall document all user interaction with the system." Since clicking a menu item or toolbar button is an "action-response" type of behavior, it seems to make sense that this should be documented in its own use case.
 b) The UI specs, as part of the responsibilities of the menu.

On a final note, use cases may not be intended to be used as the instruction manual, but according to Doug Rosenberg of ICONIX, the use cases should match up with the sections of your user manual, since the intent of use cases is to document the behavior of the system from the user's perspective.

WHEW!  Now that I've said all of that, anyone have any input in terms of where this info should go?

[DMT]

This was an interesting piece of Use Case Driven Object Modeling with UML (Doug Rosenberg):

"You should keep one overriding principle in mind at all times in your effort to identify use cases: They should have strong correlations with material in the user manual for the system. It should be obvious what the connection is between each use case and a distinct section of your user guide. This reinforces the fundamental notion that you are conforming the design of the system to the viewpoints of the users. It also provides a convenient summary of what 'use case driven' means: Write the user manual, then write the code."
- Page 41 (emphasis is his).

Just thought I'd throw that out there because we're trying to implement the ICONIX process outlined in this book...

[Tjerk]

Hi DMT,

From what I see, you have more experience than I do, but there are some that I noticed:

• In my point of view, Use Cases are intended to be specifications, not design. So if you need to specify the system in such a way that a programmer can directly work, then you should give them a detailed design. That design can be worked out using components, classes, sequences, interfaces, etc. But not using Use Cases I guess.
  
• I like the remarks on Use Cases matching structures in the User Manual, but yet again Use Cases specify what and a User Manual specifies what and how (a mix of specifications and design).
  
• Locking up programmers is an ideal situation, be carefull not to spend lots of dollars creating the absolute specifications and designs. I guess you already know, but leaving the details to be (dis)covered by the programmers (maybe through interaction with client, architect or analyst) might save costs. But then, they should (as always) make their choices explicit and available for their clients.
  
• Choosing UML centric documentation doesn't mean you have chosen a process or a documentation standard! Look for the UML process forum for more discussions on this subject.
  

Greetings,
Tjerk

[Fintan]

- There is a menu item under the File menu called "Open Company Database." If the user triggers this option, the system displays a dialog, allowing the user to select a company database.
- There is an "open document"-looking button on the toolbar that triggers the same action. It looks like a blank page, just like the New Document toolbar button in MS Word.
- The File menu lists the 4 most recently used (MRU) company databases. If the user triggers one of these options, it just opens the company database.

HI DMT,

For the first and third of these options I would use one use case e.g. "Retrive Company data".

The first step in my use case would be something like :
"The DBRetriever selects the option to retrieve a Company database".
This avoids the design decision as to 'how' the DBRetriever (or whatever you call your actor) will select this option.

For your second option you may use a use case "Open Document" and the the wording :
"The system retrieves the company data" as a step within the use case.

Does this help?

Fintan

[DMT]

There are two things I'm trying to figure out in my mind. In the context of this fictitious example, they'd be:

1. How do I document the fact that one of the ways the user can open a database is by clicking File, Open?
2. How do I document the fact that the other way is by clicking the "open folder" icon on the toolbar?

This is the user interacting with the system. It's a scenario that needs to be tested.  For me, this points to the need for a use case to encapsulate the behavior.

So, I guess the question is, why avoid use cases such as:

Select Menu Option
Click Toolbar Button

?

[Fintan]

There are two things I'm trying to figure out in my mind. In the context of this fictitious example, they'd be:

1. How do I document the fact that one of the ways the user can open a database is by clicking File, Open?
2. How do I document the fact that the other way is by clicking the "open folder" icon on the toolbar?

This is the user interacting with the system. It's a scenario that needs to be tested.  For me, this points to the need for a use case to encapsulate the behavior.

So, I guess the question is, why avoid use cases such as:

Select Menu Option
Click Toolbar Button

?

HI DMT,

Use Cases are only for capturing Functional requirements.  In your case the function of the system is the same whether the user chooses a menu option or clicks a toolbar button.

Whether you use menus, or toolbar buttons, or both is part of User Interface design.  While you are correct in the assumption that you should test both, you should not be concerned with design issues when you are defining your requirements (use cases).  Once you have completed your use case you can start designing the code to implement this functionality - here is where you will discover that you have to ways to fire a particular use cases.  It is at this stage that you will create / modify your tests to reflect this.

Regards,

Fintan

[DMT]

Actually, use cases REALIZE functional requirements by explaining how an actor interacts with the system. They are NOT functional requirements in and of themselves.

For example, these are functional requirements:

- The system shall allow the user to browse a list of books.
- The system shall allow the user to search for all books by a particular author
- The system shall allow the user to search for all books in a particular category
etc...

ANYHOW, it doesn't really matter.  All that matters is capturing the complete functionality of the system to be built, to be used by programmers, architects, user documentation writers, marketing, and the QA team.

I would agree with you that the UI requirements could capture the idea of a toolbar button and a menu button.  But then don't we get away from the idea of "Use-case driven development?"  Aren't use cases supposed to capture 100% of the interaction between an actor and the system?  Is the system not supposed to be completely testable simply be exercising all use case basic and altenative flows?

I guess I'll ask you this. Where would you place the following statement in the scope of the specifications for the system, and where would it go in Enterprise Architect?
"If the user clicks the File | Open menu item, the system shall initiate the Open File use case."

[kelly_sumrall]

DMT,

I think you are taking an approach that is too detailed, unless the document is the goal.  The approach you are taking is similar the line of thinking that to get from point A to point B, you must first get to point 1/2 A.  From there you must get to point 1/2A + 1/2(1/2A), and half again and again and again until you discover you'll never make it to point B.  If you spend too much time creating the details as described, the developers a Microsoft will have time to create a plethora of alternate methods of starting the use case you haven't planned/documented.  Don't get me wrong, at work I'm accused of being too detail oriented, and from reading your posts, it sounds like you have a bit of experience in documenting.  I think the methods of initiating a Use Case are a wrapper, a thin wrapper at that.

[Fintan]

Actually, use cases REALIZE functional requirements by explaining how an actor interacts with the system.

I am sorry DMT I cannot agree with this.  Use Cases do not explain HOW anything happens.....  Use Cases explain WHAT happens.

I would agree with you that the UI requirements could capture the idea of a toolbar button and a menu button.  But then don't we get away from the idea of "Use-case driven development?"  Aren't use cases supposed to capture 100% of the interaction between an actor and the system?

There are many models in a project.  The key to "Use-case driven development" is that Logical models and Dynamic models, etc. are derived from the Use Cases.  There is a model which is called the 'User Experience' Model.  This is a model which is derived from the Use Cases that details the User Interface, and could include the details about File | Open vs clicking on a Toolbar button.

Since the User Experience Model is derived from the Use Cases as part of UI design - we are still on track for "Use-case driven development"

Regards,

Fintan

[DMT]

To follow your idea through in terms of EA, what type of diagram would the User Experience diagram be, and what types of UML elements would appear on it?

As far as use cases go--small semantic mistake on my part.  However, I would still contend that functional requirements specify what functionality the system must provide, whereas use cases specify the scenarios that allow to user to exeperience that functionality...

[DMT]

Kelly:

This is my issue: you're right, these are small details.  My problem remains: where do they go?  I can't just say, "'Well, those are small details, and I'll just leave them OUT."  

They SEEM to be too small to belong in a use case, but how can I accomplish my goals, which are:

1. Document the fact that these actions cause the system to initiate a use case
2. Keep my use cases free of descriptions of the action(s) that initiate them?
3. Document this behavior in such a way that it will get "discovered" by the QA team and not lost, buried down with other myriad details.

Trust me--I don't yet have the answer!  I'm just trying to figure out what others have done.  Unfortunately, so far, no one has given me an answer other than something that sounds like, "that's a detail that you don't need to document."

It ALL needs to get documented, or the system cannot be built.  Again, my acid test is--if I got hit by a bus tomorrow, the development team should be able to pick up my design documentation and build the system EXACTLY AS I INTENDED IT TO BE BUILT.

So, I would expect to open up the app and see a toolbar and file menu, and when I click File | Open, I'd expect the Open File use case to be kicked off.

*grin*  It's a tricky little (emphasis on the LITTLE) problem but it's really buggin' me!  When I was writing SRS documents, which were light on use cases, I just stuck this in the UI spec along with the menu option description.  I guess it still makes sense to have it there--I'm just trying to figure out where it belongs in EA!

Thanks everyone for the input--I'm not trying to be difficult.  I'm just trying to find an answer that works in the context of our design.

Dave

[DMT]

I've just re-read some of my posts and the various replies, and I'm wondering if perhaps I could put our project into perspective, so you don't think I'm simply being too detailed on a small, 3-month project.

We are re-writing our product to upgrade the technology from a desktop database to a .NET/SQL Server client/server application using Windows Forms. The original product took about 15 man years of effort to complete, and resulted in a useful lifetime of about five years.  The product sells for approximately US$6,000 per user.  Our number one selling point: ease of use, due to our extremely detailed deisign process to create the user interface.

Translation: The most important part of our product is the user interface.

During the development process for the original system, I took an approach much like the one that seems to be described--just cover the major pieces of functionality, and skip over some of the "smaller" details.

That didn't work out so well. Fictional example:

Me: "Where is the File | Open menu item?"
Programmer: "What File | Open menu item?"
"The one that I just assumed was going to be there.  Don't you see it here on the screen capture?"
"Is there anything in the design documentation about it?"
"Um. No."
"If it wasn't in the design documentation, I didn't create it."

We've now spent about 6 man years in the design and development process for the replacement product. I have written 750 pages of SRS documentation (Software Requirements Specification, outlined in Managing Software Requirements, by Leffingwell & Widrig) for the first 50% of the product. (It's not exactly light on functionality).

The expected lifetime of this product is ten years.  Again, as with the original product, the user interface is the most critical part of the system.

So, as you can see, this is why I'm so hung up on this. The #1 priority is an aspect of the design I don't have a firm grasp on in terms of handling in EA.

You may ask why I'm changing our process. The main reason is that since the SRS was largely requirements driven, as opposed to use case driven, it was easy for the development team to "get lost" in the documentation. Many times, it seemed like I was the only one who understood the full scope of required functionality--a depressing result after spending 12 months writing the SRS documentation. The primary reason: there was no "entry point" into the process of deciphering the documentation.

My new thought: Stick with the general outline of the SRS package, but make the entire set of functionality of the system driven by use cases. Use cases become the foundation of almost everything:
1. Conception of how the user will interact with the system
2. User interface (designed hand-in-hand with the use cases to support the scenarios they outline.)
3. Implementation
4. Testing
5. Scheduling
6. Documentation

So anyway, that's the backstory. Hopefully it will help you understand the importance of capturing ALL of the details. Six years from now, someone who doesn't yet work here needs to be able to crack open the design documentation and answer the question:

"What did the designer originally intend the File | Open menu item to do?"

[kelly_sumrall]

DMT,

Just a thought since I am at a different computer and can't pre-test.  You may be able to use constraints for your use cases and have the constraint explain the detail of the trigger event.  You may even be able to add a 'Trigger' type constraint to the constraint types dropdown.

On a project I've been working on I did something similar, but instead of the use case, I captured the trigger event in the sequence diagram using System as the actor and a constraint of a 5 minute timer event.

If this doesn't give you exatly what you are looking for, maybe it will spark some ideas out there.

The answer IS out there!