Using VisualAge UML Designer to capture and analyze requirements

Not having any requirements myself, it was rather convenient to receive this e-mail from my younger brother addressed to his geek relatives:
"How are you going tech dudes? I have an idea that I thought I might kick around - how about a 'muso's friend' device that runs a constant recording buffer so that you can hit record and it captures the last 'x' amounts of minutes? with these digital devices getting more able at capturing longer periods with lesser amounts of memory I thought it might be feasible... getting sick of missing some golden moments and i wish them back :) anyone got any contacts in r&d? cheers,
Glenno"

Nice idea, but (perish the thought) perhaps a little feature-itis might make for a more instructive article, so expanding on Glenn's theme a little...

Take Notes

There is already something called "Musician's Friend ? The World's Largest Online Music Gear Company" and I am always wary of any product whose initials shorten to MF, so for the time being I have re-christened Glenn's device "Take Notes". Before inputting the requirements we need to create a model. In line with the Redbook instructions we specify model name "Take Notes Model", namespace prefix "TN" and application name "TNTakeNotes" as shown below. In the LazyWeb-style common pool for requirements discussed in an earlier article, there would have to be some control over the assignment of namespace prefix values to help ensure namespace clashes are kept to a minimum.

The requirements I came up with for a PC-based version of Glenn's device were:

• Record into endless loop
• Save region of endless loop
• Play back named track while recording into endless loop
• Extract take to named track
• Merge related named tracks to new track
• Play back/mix multiple named tracks simultaneously
• Delete named track

The details of these requirements can be seen in the screen prints, however they are not really important for the purposes of this article.

Now let's move on to the use-case aspect of UML. Use-cases pre-date UML. In the old days I heard you would write out scenarios in normal text, somewhat like telling the "a man walks into a bar..." jokes, as a set of actions performed by players. After telling the story of a stereotypical task you could go back through the text highlighting the nouns and verbs in different ways, and potentially the nouns would become the objects and the verbs the methods. As we will see later this is still partly the method used. Use-case diagrams, in turn, seek to place stickmen around a diagram representing the system, with the stickmen as the main actors in your story and interactions between actors and tasks represented by lines. Despite the "every picture tells a thousand words" truism, text still plays the more important role in the overall description of the behavior.

The description at the start of chapter 5 of the Redbook is probably as clear as it possibly can be regarding use-cases, but again the perspective differs from our perspective. Read the first page of Chapter 5 anyway.

Given the set of seven requirements we have listed above, requirements that basically correspond to blocks of actions, the temptation is to start creating use-cases named after each of the requirements. In fact this is what I did initially, as can be seen by studying the screen prints below. However, this is not the best idea. Remembering that you want to eventually put these use-case names into an oval on a diagram shorter names are best.

A use-case is a specific task that can be broken into a number of steps, but whilst still suiting a natural language description, the style of that language should be slightly different to the style used for requirements. Think George Orwell, think short sentences and simple words conveying big ideas. It is OK to have flowery and impressive sounding requirements, after all, they have to "signed-off" by the end-user of the system, but use-cases are about baby-steps. You don't want to have to fight your way through nested sub-clauses to identify actors and relationships later.

In keeping with this approach I renamed the use-cases I had already created thus:

• "Record into endless loop" became simply "Record"
• "Playback endless loop" became "Play"
• "Save region of endless loop" became "Save"
• "Play back named track while recording to endless loop" became "Record accompaniment"

to which was added:

• "Play accompaniment"
• "Save accompaniment"
• "Preview mix"
• "Mixdown"
• "Delete"

The details of the use-cases can be seen in the following screen prints, although again they are not really significant to the point of this article.

NOTE: The Visual UML Designer provides both use-cases (the textual description) and use-case diagrams as separate modeling elements to capture the functional elements of the system, and the Redbook suggests the text be entered ahead of the diagrams. Other tools such as Rational XDE provide a more visually unified approach with diagrams and text as panes on the same window rather than separate windows, however the tendency with that tool is to draw first and document the drawing in the text pane. I have a suspicion that the approach of the Visual UML Designer captures the use-case in a manner that reflects the end-user steps more closely, but that the XDE approach is more readable by someone looking at the documentation later.

The next step suggested by the Redbook is to link the use-cases to the requirements, as in this use-case satisfies this/these requirements. This stage provides a sanity check in that if you have entered a use-case for which you cannot find a requirement that it satisfies, either it represents steps that do not need to be supported, or a requirement was missed in the first stage. Let us review our use-case linkages.

The way I see it:

• "Record" satisfies "Record into endless loop"
• "Play" satisfies "Save region of endless loop"
• "Save" satisfies "Save region of endless loop"
• "Record accompaniment" satisfies "Play back named track while recording to endless loop"
• "Play accompaniment" satisfies "Extract take to named track"
• "Save accompaniment" satisfies "Extract take to named track"
• "Preview mix" satisfies "Play back/mix multiple named tracks simultaneously" AND "Play back named track while recording to endless loop"
• "Mixdown" satisfies "Merge related named tracks to new track"
• "Delete" satisfies "Delete named track"

Note that there was no specific requirement to be able to play back either the endless loop or a single named track. It would, of course, be a pretty lame system without either of these facilities, however I considered them implicit requirements and so they were left implicit.

Having linked our use-cases to our requirements (see chapter 5.1.2 of Redbook for details), the next step is the "hook" of this article, that analyzing the use-cases can produce that running start we need for the next stage of development (and more OS/2 applications). Chapter 5.2 of the Redbook conveys the ideas well. If we have entered comprehensive use-case text into reasonably simple sentences the analysis should not be too difficult. Let's look at the "Record accompaniment" use-case as an example.

The obvious first "actor" to create in our Take Notes model is the musician. Similarly, the endless loop represents the most obvious "thing". The next entity to classify, and the most awkward is accompaniment. This object is difficult because it exists as a property of a recording inside the endless loop which it retains when it that recording is extracted to a named track. So is it a "thing" or an attribute of another "thing"? For the moment, since we are not looking to jump straight to class diagrams and hierarchies, let's just call it a "thing" (and make notes). Similarly the words take and section referring to areas within the endless loop are probably best labeled "things" for the time being as well. The ability of VisualAge UML Designer to add objects on the fly by marking text and creating links is extremely useful as you work through the use-cases identifying nouns and classifying them. Most of the nouns should turn out to be actors or things, however in the Take Notes model I did manage to identify at lease one concept, corresponding to the phrase "cycle time".

The remainder of Chapter 5 of the Redbook covers what steps to take in what order, and how many iterations to perform to achieve the appropriate level of cross-referenced documentation, far more comprehensively than this article. Rather than repeat it I will try to describe the net effect of following those instructions versus not following them. Suppose you use the "textual" stage of analysis to determine which use-cases are in fact part of other use-cases. For an example you might decide "Preview mix" is part of (is used by) "Record accompaniment" - since you have to be able to hear the track(s) in order to accompany them. When you come to create the use-case diagrams (covered in Chapter 6) the "Hide/Show Relationships" option on the context menu of the "Record accompaniment" use-case figure will bring up an option to automatically create the "Preview mix" use-case figure on the diagram with the correct relationship. The screen print below shows the use-case diagram "generated" via the relationships already built in the model.

If you choose not to analyze these relationships at the "textual" stage you can still create the relationships via the diagrammer, but the diagram is then creating the model whereas the other way the model all but creates the diagram for you. Both approaches are valid and can produce the same results, however for the novice user the level of intimidation associated with using words seems lower than that of using unfamiliar diagramming tools. Of course you still have the facility to lay out the diagram for the best appearance and legibility with either method.

At this point in the analysis there exists a number of use-cases with nouns highlighted. It is tempting to say that this is the point at which non-technical people should seek technical help. Chapter 7 of the Redbook goes into the far more technical sounding "Responsibilities and Participants (Collaborators)" and outlines the 4 different kinds of responsibilities a thing can have, which begins to sound much more intimidating and have much more impact on the design stages of development - something best left to technical people. However, there is one last trick to try. The first of the four types of responsibility listed is an ability to perform an action. As Chapter 7 says VisualAge UML Designer provides the great facility to browse the use-cases a particular "thing" is used by. For example, taking the "Browse" and "Used By" options from the context menu for the "thing" endless loop in our model shows the following screen.

This suggests that the "thing" endless loop might meaningfully be able to perform the actions "play", "record", "record accompaniment" and "save". Marking up the verbs from each of these use-case scenarios should additionally provide a further running start for this stage of the analysis. For instance, use-case play has a sentence with "mark start and end points" in it, suggesting "mark start" and "mark end" would be good candidates as responsibilities of endless loop. Despite the fact that method names are now tentatively being assigned to classes deep inside the tool, this kind of analysis still really only requires a command of grammar - that is the ability to recognize a verb.

At this point I hope this article has convinced readers that VisualAge UML Designer can provide non-technical people with the ability to provide technical people with far more analytical artifacts presented in far more useful a manner than a few e-mailed sentences. I hope my brother reads this! For the OS/2 community, the "free for non-commercial use" nature of VisualAge for Smalltalk has presented a powerful tool to a community in need of all the self-help it can get.