Detail Level of Use Case Documentation [closed]

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 -
_{(source: agilemodeling.com)}

Answer 2

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.