Detail Level of Use Case Documentation

Question

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?

Answer 1

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 -

Answer 2

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.

Answer 3

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.

Answer 4

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)

Answer 5

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"