views:

2346

answers:

5

I am making a strong effort to discipline my projects and create a Vision/Scope document at the onset. Included in this are the use case diagrams. Just listing out the use cases has really helped me fully see all the requirements that the customer is asking for, and it has opened up dialog.

I am wondering about how detailed the use case should be. If I am making a web application and the user will login to see a report, do I list all the columns on the report in the use case description?

If not, then when would I document those details?

+3  A: 

the advantage of use-case diagrams is that they are simple and end-users can read and understand them

the columns to go on a report are part of a design or requirements specification (details of a feature, in agile terms) and do not belong on a use-case diagram

anything that clutters the use-case diagram belongs somewhere else

where? it doesn't matter, as long as it's a consistent place and you know where to find it ;-)

to remind people what a use-case diagram looks like - and why there is no room for spurious details -

Steven A. Lowe
I guess my answer doesn't take into account the difference between the use case and other parts of the spec. I'm fine with that because I prefer a single detailed spec over a formalized use case definition. But that's just me.
jeremcc
Man -- I'd like this college -- No 'take exam' use case!
toolkit
+2  A: 

If you know what columns should be included, then yes, put them in the document. If you have to think about it a bit first, then do so and document it. It will save the programmer having to think or ask about it later, which makes the whole process more efficient.

However, if you truly don't know what columns should be included yet, because you don't know enough about how the whole system will play out once development is underway, then don't worry about it and just say "Specific columns TBD."

You can't know everything up front, but definitely document what you do know.

jeremcc
have you ever seen a use-case diagram? there is no room for this kind of detail, and it defeats the purpose... http://www.agilemodeling.com/images/models/useCaseDiagram.jpg
Steven A. Lowe
A Use Case is a document. A Use Case Diagram is the pretty picture. You really need both if you're talking about documenting requirements.
ScArcher2
Yes, I have seen use case diagrams, but I have also seen use case documents that include text descriptions of processes with sections like Goal, Actors, Precondition, Success Condition, etc. My answer was more related to those, since it obviously wouldn't make sense to put it in the diagram.
jeremcc
The diagrams are tools to help explain the text. I've seen use case docs that have no diagrams. e.g. A use case for logging into a system might be:1. User enters user id and password (return error 123 if field is blank)2. Authenticate user (return error 456 if this fails)3. Navigate to main page
Elie
my apologies, i answered from an agile perspective, where a use-case diagram is a starting place to discuss features, and there is never a use case, requirements, or any other 'document' to kill trees and get out of date ;-) [plus the question was specifically about a use-case diagram]
Steven A. Lowe
Things don't have to be on paper to get out of date.
Bernard Dy
+3  A: 

A use case, where I work, is a description of the application from a user's perspective. At that level, it is very detailed. So, in your example of a report, the use case would describe the layout of the report, what data is shown, in what order, and so on. What the use case does not tell you is how that data is acquired, or where it comes from.

Another way of looking at it is to think of handing the use case to a tester. They can test anything in the document (black box testing) and register it as a defect. So if certain data is supposed to be shown under certain conditions, that case should be specified in your use case so that it can be tested.

Other documents you may want to create to complete the picture are what we call the SAD (Software Architecture Document) and NFR (Non-Functional Requirements). The SAD would describe from a software design perspective how you are going to program the solution, what technologies you are going to use, and what algorithms are required. The NFR will include things such as recovery from a software or hardware outage, response times, and so on.

Elie
SAD and NFR? LOL! Who named these things? do you also have a Software Hierarchical Interface Tree Diagram? ;-)
Steven A. Lowe
Not a clue... must be the Software Architecture Team
Elie
A: 

Use case description should be between:

  • Low details: so that user understands it, and thinks: "How easy is that to do"
  • High details: No open possibilities (Detailed description of what happens after each step)
Peter Gfader
A: 

Building usecase diagrams with UML notations help us to understand & specify requirements quickly, Usually Use case diagrams can be drawn infront of team of software Engineers to quickly understand the situation.

Actually, A usecase should be in written format. It has three formats.

  1. Brief
  2. Casual
  3. Fully Dressed

In case of a report, Report format & specification should be attached with SRS document, So that testing can be performed accordingly.

For details... See "Applying UML and Patterns: An Introduction to Object-Oriented Analysis and Design and Iterative Development By Craig Larman"

naveed