Here's a several part list of thoughts. NOTE - this is very waterfall style. Your mileage will definitely vary if you are working an agile methodology.
Tools:
- First, choose between the big fancy tool and the readily available tool. UML tools have a big learning curve, which is worth it if you need flexibility, links to other artifact or the need to present in many different formats. It's better to use a simple text editor and drawing tool if you just want to throw up a quick document and just focus your time on the content.
- UML Editors - I've used and liked Rational Rose, but my take is that it's falling behind the curve. I like that it treats UML diagram elements as data objects than can be manipulated under the covers, but all that infrastructure can be like trying to drive a tank to the grocery store. I've used JBuilder 2007, as well, and didn't like it as much, although it does allow linkage to external documents. For almost any UML Editor, plan extra time to export your use case collection if you have to present it to anyone who doesn't have the tool.
- A drawing tool (I love Visio!) and a text editor (I've sold my soul to Word) give more flexibility and allow you break the rules. Most UML editors will try to force a common layout or format on what you write. In many ways, I prefer the no-new-tool approach, since it lets me bend the rules of Use Case diagramming to do what I want.
Books:
My penultimate guide has been "UML Distilled" by Mark Fowler for diagramming. I use a template for use cases that is an artifact of my company. It includes the fairly standard:
- primary and secondary actors
- flow of events
- entrance and exit conditions
- trigger
- quality requirements
I also found it useful to have:
- associated requirements - if requirements are pre-written
- notes and special cases
- a question section - when working with a new product or new team
Guides:
I really liked this:
http://www.bredemeyer.com/pdf_files/functreq.pdf
But I've only just read it.
Alot of what I've done has come from years of doing it. My general thoughts are:
- Start big - write down possible titles for use cases as you start reading whatever documents you have and talking to whoever you need to talk to. "Whatever" and "whoever" are very broad - in some industries, pre-use case reference material is fairly formal. In others, it's just talking to users or managers and getting thoughts.
- Focus on the actual work - there's probably all sorts of installation cases, error cases, upgrade cases, logging cases - don't worry much about them. You need them, but don't waste the time just yet.
- Refine what you can - some stuff will start to get obvious, write down what you can, descriptions, primitive flows of events. Don't worry much about actors - take a guess, but expect it to change.
- Develop questions and document them - sooner or later you'll be able to ask someone some questions, so keep a collection that references the current use cases.
- Try some diagrams - they usually point out what's missing in the sequence of events.
Now's the time to get feedback. Put them in a readable form, spell check, grammer check and find a way to bundle diagrams and use cases together. Then find people to vet your idea. Ideally this would be users, but that's not possible in every industry. Whoever serves as your customer representation should be involved. Collect comments, and make notes of places of confusion.
Now it's time to reiterate:
- Repeat all the bullets above, and go down a level of detail in existing use cases.
- Fix comments
- Refactor use cases - do they make sense in the bundles they are? Look for includes relationships, extends relationships and pure redistrubution of flows of events into more or less use cases.
- Focus in on the supporting use cases
Now, it depends on your goals. You can continue the review/revise steps until there is a satisfactory level of consensus. Or you may need to get stakeholders in a meeting together. At some point, you decide enough is enough. Not that changes may not occur, but that modifying the use case is no longer the primary task.
This is the point at which I prefer to write requirements. At this point, I understand the functional flow enough to try user level requirements.
I also like to link requirements to use cases. I may include the requirements with the use case text, although there will be a requirements repository somewhere aggregating all the requirements. Ideally, I have a requirements database that allows me to link the requirement to an enumeration for my use cases. I work in a highly structured, artifact driven environment. In that world, it's wonderful to have the use case be linked to requirements, because the use case serves as a great jumping off point for developing system tests. It also lets me link the use case to the design work, and thus see a link from requirements to use case to design.
I don't recommend linking the use case to the design on a 1:1 basis. I've done this, and I usually find that way too much meaningless design work takes place, at the deficit to really thinking out the harder/weirder elements of design that aren't readily represented by use cases. Instead, I'd say find a pattern of use cases that are all fairly similar, develop a high level design pattern for it, and then move on.
Effort:
I've found that:
- The first pass should be very few people - 1 if possible, maybe 2-4 working in very close collaboration.
- The second pass can be a bigger group, if the first pass was very solid.
- The first and second passes take almost equal amounts of time.
- If the use case cycle was detailed and solid, the requirements writing will be shorter than the use case development cycle.
General Theory
I've used use cases in one of two ways:
- Comparable to CONOPS - as a replacement for a Concept of Operations - in this case, use cases are very high level. They don't go to the level of suggesting direct GUI implementations, they just specify generalities of what the user does and gets from the system. They are written before the requirements and a separate user interface design cycle must occur after the requirements are written.
- Functional Spec - if a CONOPS and requirements document already exist, use cases can build on these to provide details of exactly how the HMI will work. This can go hand in hand with user interface design, but this level of detail requires that some up front concept of operation work has already been done and documented.
Be aware of what level of detail you are working on. Going too detailed, too fast, will result in a massive amount of rework. Going too high level when detail is required simply results in mass confusion and later bugs in design and code.