Use Cases cause a lot of confusion for many people new to UML and SysML. The OMG UML Infrastructure specification calls Use Cases "a means for specifying required usages of a system. Typically, they are used to capture the requirements of a system, that is, what a system is supposed to do." (OMG Unified Modeling Language (OMG UML) Superstructure, V2.1.2, p. 585). This definition seems a bit academic, so let me try to bring some practical world experience.
Let's be clear: Use Cases ARE requirements. They provide much more than simple shall statements, however. From a Systems Engineering perspective, think of about the problem space this way: a Request for Proposal or Statement of Work provides the requirements for any competitor's solution, but your Use Cases explain your organization's specific solution. They list the capabilities of the system. You will use the descriptions to allocate functionality to different parts of the system. Taken together, the Use Cases described your proposal. Each of the functional shall statement requirements should trace from a Use Case.
Since Use Cases detail the system requirements, they tell what the system will do, not how the system will do it. Use Cases do not show functional decomposition, nor do they specify how to write the code.
Another confusing aspect of use cases are the relationships « extends » and « includes » . I am not going to spend much time describing these here because it is an academic argument. Whether you show a capability as « extends » or « includes » is almost irrelevant. Either way, you will need to detail the additional Use Case. Therefore, I only use « includes » ; and then I only use it when multiple Use Cases require the exact same capability.
A Use Case's meat exists in its description. The description shows, step by step, what the system does to implement a capability. It shows the response to external stimuli (Actors). As important, a Use Case description shows the exception conditions when the normal flow of events does not happen. These discussions of exception handling show the real power of Use Cases. They force the engineers, both Systems and Software, to think about the exception conditions up front.
In the next two sections, we will discuss different methods for detailing Use Cases. The first method uses text. The second uses and Activity Diagram.
Tuesday, December 22, 2009
Saturday, December 19, 2009
Why Model
The model specifies what a system does and how it does it. Logically, therefore, one starts modeling by deciding what the system is going to do. In traditional, document-driven development, one starts with a Request for Proposal (RFP) or Statement of Work (SOW), writes a proposal or System Specification Design Document (SSDD), writes the System Requirements Specification (SRS), and finally writes a System Design Document (SDD). This methodology has worked for the last 50 years and I'm not suggesting that modeling should replace it. For one reason, many contracts require text deliverables. Rather, modeling augments this process.
Text is a very poor way for engineers to communicate. For the most part, engineers are visual people. If I were to ask you to go to whiteboard and describe the system you are currently working on, odds are pretty good that you will not write a bunch of paragraphs. You will draw some circles and boxes and maybe some arrows to describe the flow. In fact, the main reason we text documents to communicate is because computers come with keyboards.
Another problem with text is that words have different meanings in different industries and different parts of the country. Take the word "fixing." It might mean repairing. Or, especially around the holidays, it might refer to side dishes. Here in Fort Worth, Texas, it means you are getting ready to do something.
Not only do words have shadow meanings, but not all of our coworkers are native English speakers. We may work with colleagues overseas. More likely, at least one team member grew up speaking a language other than English.
Another problem with text-based requirements is how we were all taught to write. Each of us had a high school English teacher, for me it was Miss Feage, who said "vary you sentence structure" and "use descriptive verb." While this advice applies when writing the Great American Novel, it does not apply when writing the Great American Requirements Specification. For a requirements specification, we expect "subject shall requirement." Unfortunately, I have yet to see a customer document written in this format.
Building specifications in UML and SysML avoid all of these problems. UML and SysML are graphical languages. Engineers and Computer Scientists relate better to diagrams than to text. Furthermore, the graphics help engineers see the part of the system under consideration in a single view. This view helps them identify missing exception conditions and inconsistencies.
UML and SysML have very distinct syntax. This syntax is designed to specify structure, interaction, and behavior in a distinct manner that, if used properly, is not open to misinterpretation. And when it comes time to generate the deliverable documents, the better modeling tools support generating the documents directly from the model.
Bottom line: modeling is more natural than text, will help you avoid and identify errors earlier, and still lets you follow your existing processes.
Text is a very poor way for engineers to communicate. For the most part, engineers are visual people. If I were to ask you to go to whiteboard and describe the system you are currently working on, odds are pretty good that you will not write a bunch of paragraphs. You will draw some circles and boxes and maybe some arrows to describe the flow. In fact, the main reason we text documents to communicate is because computers come with keyboards.
Another problem with text is that words have different meanings in different industries and different parts of the country. Take the word "fixing." It might mean repairing. Or, especially around the holidays, it might refer to side dishes. Here in Fort Worth, Texas, it means you are getting ready to do something.
Not only do words have shadow meanings, but not all of our coworkers are native English speakers. We may work with colleagues overseas. More likely, at least one team member grew up speaking a language other than English.
Another problem with text-based requirements is how we were all taught to write. Each of us had a high school English teacher, for me it was Miss Feage, who said "vary you sentence structure" and "use descriptive verb." While this advice applies when writing the Great American Novel, it does not apply when writing the Great American Requirements Specification. For a requirements specification, we expect "subject shall requirement." Unfortunately, I have yet to see a customer document written in this format.
Building specifications in UML and SysML avoid all of these problems. UML and SysML are graphical languages. Engineers and Computer Scientists relate better to diagrams than to text. Furthermore, the graphics help engineers see the part of the system under consideration in a single view. This view helps them identify missing exception conditions and inconsistencies.
UML and SysML have very distinct syntax. This syntax is designed to specify structure, interaction, and behavior in a distinct manner that, if used properly, is not open to misinterpretation. And when it comes time to generate the deliverable documents, the better modeling tools support generating the documents directly from the model.
Bottom line: modeling is more natural than text, will help you avoid and identify errors earlier, and still lets you follow your existing processes.
Use Case Diagrams, Actors and Associations
Let's talk a little more about actors.
Actors represent something outside the system that either affects the system or the system affects. The significance here is that an actor is outside of the system. You are not going to build it. You are not going to model its behavior. Even though UML and SysML use stick figures to show actors on diagrams, all actors are not people. Actors may represent people (for example, the user) or they may represent hardware (a sensor or an effector) or they may represent another subsystem.
Any of you who have attended any of my classes know that I am about to get on my soap box now. Hard engineering disciplines (electrical, mechanical, chemical, civil) will never take Systems and Software engineers seriously as long as we use these silly indicators and cutesy terms (e.g., fuzzy logic). Therefore, if you are going to show use case diagrams to your colleagues or customers who are not fluent in UML/SysML, change the picture of the actor to what it represents in the real world (a tank, a letter carrier, the physical actuator). Better modeling tools let you make this substitution (if yours does not, contact me and I'll put you in touch with a sales guy). OK, now I'll step off my soapbox and go back to the discussion.
When developing systems, actors represent anything you are not getting paid for. In an IT system, the actor may represent the server -- or better, an application running the server. In an aircraft flight control system, use an actor to represent the pilot (not the stick because it is part of the aircraft and generally falls under the auspices of the flight control subsystem), the inertial navigation system (it is not part of flight controls), and the surfaces (when you execute the model, you want to confirm they are moving the correct direction).
When developing software, use cases represent a single feature of the code (more on this when we discuss Use Cases and the Development Process). In these cases, the actor represents the other parts of the code that interact with that feature. Let me clarify. A reusable machine control framework includes the concept of generic inputs and outputs. No matter how the physical hardware works, the application interfaces with I/O using the same (virtual) calls. The use case Read_Discrete_Inputs has an association with a Client actor. This actor represents any part of the code that requires a discrete input. By definition, the Client is internal to the system, but it is external to the feature. Therefore, as far as Read_Discrete_Inputs is concerned, Client is external. In other words, your point of view determines internal versus external.
Associations show the virtual connections between actors and use cases. They indicate which use cases an actor affects and which actor the use case affects. Most, but not all, use cases have associations with actors.
Associations provide another purpose when reviewing the model. They indicate the potential interfaces. Specifically, the association between a User actor and use case indicates that the system requires some form of user interface -- a GUI, a push button, a retinal scanner. It forces the Systems Engineer to think about what may be missing from the overall specification.
One last point, in the early days of the UML, we showed associations as arrows. These arrows caused misunderstandings and provided little additional information. Therefore, I recommend that you show the associations without arrowheads.
Actors represent something outside the system that either affects the system or the system affects. The significance here is that an actor is outside of the system. You are not going to build it. You are not going to model its behavior. Even though UML and SysML use stick figures to show actors on diagrams, all actors are not people. Actors may represent people (for example, the user) or they may represent hardware (a sensor or an effector) or they may represent another subsystem.
Any of you who have attended any of my classes know that I am about to get on my soap box now. Hard engineering disciplines (electrical, mechanical, chemical, civil) will never take Systems and Software engineers seriously as long as we use these silly indicators and cutesy terms (e.g., fuzzy logic). Therefore, if you are going to show use case diagrams to your colleagues or customers who are not fluent in UML/SysML, change the picture of the actor to what it represents in the real world (a tank, a letter carrier, the physical actuator). Better modeling tools let you make this substitution (if yours does not, contact me and I'll put you in touch with a sales guy). OK, now I'll step off my soapbox and go back to the discussion.
When developing systems, actors represent anything you are not getting paid for. In an IT system, the actor may represent the server -- or better, an application running the server. In an aircraft flight control system, use an actor to represent the pilot (not the stick because it is part of the aircraft and generally falls under the auspices of the flight control subsystem), the inertial navigation system (it is not part of flight controls), and the surfaces (when you execute the model, you want to confirm they are moving the correct direction).
When developing software, use cases represent a single feature of the code (more on this when we discuss Use Cases and the Development Process). In these cases, the actor represents the other parts of the code that interact with that feature. Let me clarify. A reusable machine control framework includes the concept of generic inputs and outputs. No matter how the physical hardware works, the application interfaces with I/O using the same (virtual) calls. The use case Read_Discrete_Inputs has an association with a Client actor. This actor represents any part of the code that requires a discrete input. By definition, the Client is internal to the system, but it is external to the feature. Therefore, as far as Read_Discrete_Inputs is concerned, Client is external. In other words, your point of view determines internal versus external.
Associations show the virtual connections between actors and use cases. They indicate which use cases an actor affects and which actor the use case affects. Most, but not all, use cases have associations with actors.
Associations provide another purpose when reviewing the model. They indicate the potential interfaces. Specifically, the association between a User actor and use case indicates that the system requires some form of user interface -- a GUI, a push button, a retinal scanner. It forces the Systems Engineer to think about what may be missing from the overall specification.
One last point, in the early days of the UML, we showed associations as arrows. These arrows caused misunderstandings and provided little additional information. Therefore, I recommend that you show the associations without arrowheads.
Friday, December 18, 2009
Use Case Diagrams
For years, I did not see the point of Use Case diagrams. They were just a bunch of bubbles with stick figures that listed the capabilities of the system. The Use Case descriptions held the real value. They described what the system was supposed to do.
A colleague of mine, Dr. Peter Hoffmann, changed my opinion. Peter preaches that the we should think of the Use Case diagram the way we think of a table of contents of a book. It gives a quick and concise way to show a system's capabilities -- think section 3.3.1 of an IEEE specification.
A common question many customers ask about Use Case diagrams is where does one draw the boundary. I answer that how one displays Use Cases on a Use Case diagram is a function of the model's purpose and the modeler's perspective. Let me explain. For Systems Engineers, the boundary box represents everything that you bill to the customer. Therefore, if you are delivering computer equipment, include it inside the boundary and show the actor as the User.
For Software Engineers, show the boundary at the edge of your work focus. In other words, if your part of the code interfaces with an API, web service, firmware or physical hardware, show these as actors.
Another common question is how to show the Use Case description. Again, my answer is to consider your audience. Use Case description are a great way to share your understanding of the system with the stakeholders. For one project I worked for the United States Postal Service, I gave Use Cases to the head technician so that he could confirm that the machine worked the way I understood it to work. He was very comfortable with ladder logic, so I gave him Activity Diagrams. For another project, the stakeholder was a marketing/sales exec. He was more comfortable with a text description. Both methods worked well for the intended audience.
A colleague of mine, Dr. Peter Hoffmann, changed my opinion. Peter preaches that the we should think of the Use Case diagram the way we think of a table of contents of a book. It gives a quick and concise way to show a system's capabilities -- think section 3.3.1 of an IEEE specification.
A common question many customers ask about Use Case diagrams is where does one draw the boundary. I answer that how one displays Use Cases on a Use Case diagram is a function of the model's purpose and the modeler's perspective. Let me explain. For Systems Engineers, the boundary box represents everything that you bill to the customer. Therefore, if you are delivering computer equipment, include it inside the boundary and show the actor as the User.
For Software Engineers, show the boundary at the edge of your work focus. In other words, if your part of the code interfaces with an API, web service, firmware or physical hardware, show these as actors.
Another common question is how to show the Use Case description. Again, my answer is to consider your audience. Use Case description are a great way to share your understanding of the system with the stakeholders. For one project I worked for the United States Postal Service, I gave Use Cases to the head technician so that he could confirm that the machine worked the way I understood it to work. He was very comfortable with ladder logic, so I gave him Activity Diagrams. For another project, the stakeholder was a marketing/sales exec. He was more comfortable with a text description. Both methods worked well for the intended audience.
Thursday, December 17, 2009
UML and SysML Diagrams -- an Overview
UML and SysML diagrams fall into three categories: architectural, interaction, and behavioral. Architectural diagrams show the structure of the elements of the model. Systems Engineers using SysML use Block Definition Diagrams, Internal Block Diagrams to show a system's architecture. Software engineers use class and object diagrams to show the software structure. Both use package diagrams. Though not discussed by here, Deployment Diagrams and Component Diagrams also show the the structure and full under the Architectural Diagram classification.
Interaction diagrams show how model elements communicate. They include communication and sequence diagrams. Of the two, I strongly prefer sequence diagrams because they are easier to understand.
Behavioral diagrams show what the model elements do when they receive communications. Use Case diagrams, Activity diagrams, State Charts, and timing diagrams show the system's and the software's behavior.
Both UML and SysML are visual languages that use diagrams to show views of the model. But remember that the diagrams are views, they are not the model.
Interaction diagrams show how model elements communicate. They include communication and sequence diagrams. Of the two, I strongly prefer sequence diagrams because they are easier to understand.
Behavioral diagrams show what the model elements do when they receive communications. Use Case diagrams, Activity diagrams, State Charts, and timing diagrams show the system's and the software's behavior.
Both UML and SysML are visual languages that use diagrams to show views of the model. But remember that the diagrams are views, they are not the model.
The Most Important Diagrams
The other day, a customer asked what I thought were the most important diagrams when creating a UML model. Organizations new to modeling often ask the same question, so I'm going to spend the next few days answering it.
Always remember that the purpose of modeling is to help one understand the system. Both the UML and SysML are full of diagrams and subtleties that make the languages richer and more expressive, but only if the readers understand the full content. In my practice, I see developers with all levels of experience and comprehension of the UML. As one would expect, the vast majority are somewhere in the middle. They know the diagrams they use frequently very well and are less well versed in those they seldom use.
Use the diagrams most people understand: Use Case Diagrams, Activity Diagrams, Sequence Diagrams, and State Charts.
In the next few posts, I will describe each of these diagrams and how I use them.
Always remember that the purpose of modeling is to help one understand the system. Both the UML and SysML are full of diagrams and subtleties that make the languages richer and more expressive, but only if the readers understand the full content. In my practice, I see developers with all levels of experience and comprehension of the UML. As one would expect, the vast majority are somewhere in the middle. They know the diagrams they use frequently very well and are less well versed in those they seldom use.
Use the diagrams most people understand: Use Case Diagrams, Activity Diagrams, Sequence Diagrams, and State Charts.
In the next few posts, I will describe each of these diagrams and how I use them.
Subscribe to:
Posts (Atom)