Documenting User Requiremetns

[tslahetka]

I am a fairly new user of the EA tool and the UML language.  Recently I was involved with interviewing a large number of users to get their requirements for a new case/tracking management application.

As expected there are a lot of requriements.  Some are overall, general, application requirements, others are very specific to the data element to captured and they type of control to use.

What is the best way to document and capture all these elements?  It's been suggested often that functional requirements and system design requirements should not be mixed.  

I want to build use cases from these requirements.  I also want to summarize the requirements the users gave.  I need to confirm with the users that requirements were not missed, and that they are understood by us.  

I also want to compare the use cases to the requiements and make sure they we all capturred.

I would approciate any guidance you can provide.  Are there any white papers, vase stidues, or other general articles that give examples and ideas on capturing and documenting user reqquirements?

Thanks,

Tom Slahetka

[sargasso]

There are many, many ways to proceed.  Here's what we do.

[1]Go through the collected material, registering each

single requirement as an EA external requirement (using the requirement element on the custom toolbar)
[2] As we go, if it is apparent at the time, classify the requirement as a functional requirement, a persistence requirement (stuff the system has to retain between uses), a constraint (some limitation on how we can design the system, or other classifications that may be applicable to the system under study.
[3] In addition to the above, we record an initial rating for the following : user priority, difficulty and the analysts perception of the stability of the requirement (see note below)
[4] At appropriate points, review the collected requirements to ensure they are all unique and germaine to the defined scope of the project.  (if not the target release of the requirement is set to 9 or whatever.)
[5] As use cases appear, they are registered in skeletal format and appropriate rrealization links added to the related requirements.
[6] Use cases and requirements are grouped into packages suitable for review by the SME's - we try to present the requirements back in digestable chunks rater than as a huge slab document.
[7] Resolve any issues raised during the capture stage and during the reviews - represent as a draft requirements spec.
[8] Demonstrate to the users the condition that the requirements are in - i.e. we have high, medium and low requirements, some of which are stable, others soomewhat more fluid.  Gain acceptance to start on the high level design of the system based on use cases where requirements are stable, return to the analysis work - and further user interaction - on the fluid requirements.

.... design is a different issue!

NOTE: Stability is an attribute "partially supported by EA.  It is present in the automation model buty not directly accessible through the tool.



hth
Bruce

[Rob_M]

Our approach is similar to sargasso, but we also like to diagram in a low fidelity user interface when applicable. EA is great for this as well. So the process is similar to:
1. Start with a 'user-requirement' - I sometimes like to refer to this as a software feature. Examples would be: spell checker for a word processor, grammar checker, style capability etc.
2. Then, for each given feature, we generate associated use case(s). This represent the behavioral requirements - the main flow when things go right, and also the error cases when things don't go as planned.
3. Then, we mockup a low fidelity UI showing how the dialogs might look - clients are really receptive to this. They tend to like to provide feedback on a UI mockup rather than a use case sequence.
4. finally, we get into all the detailed requirements such as color, font, calculations, performance, etc.

The organization within EA is one package per feature. The use cases and the detailed requirements are traced to the feature.

The great thing about EA is that you can choose how you want to organize your elements into packages. Meaning, you can group things of a similar type together in the same package (i.e. all use cases in one package, all UI mockups in another, etc. or you can store the ones that apply to a particular feature in the same package.

Personally, I like packaging things related to the same feature together. This will ultimately translate to a unit of work that gets assigned for design and implementation to a software developer.
On the otherhand, there are systems engineers that would like all the requirements grouped together, HFE guys like are the UIs together. We can achieve both through automation scripts that extract all the UIs, or all the requirements (or even all the requirements of a particular type) into a document.

Rob

[wmac]

[1]Go through the collected material, registering each single requirement as an EA external requirement (using the requirement element on the custom toolbar)

Bruce

Bruce,

Where do you suggest us to put those initial uncategorized requirements?

And then move those requirements to other categories like formal-requirements and non-functional requirements?

Thank you,
Mac

[sargasso]

The easy answer would be to put them where ever you like!  

For teams new to EA we are proposing a standardised layout that guides them into a structure as follows:

1) Requirments View
1.1 Business models
1.2 etc
1.4 Functional Requirements
1.5 Supplementary Requirements
1.6 Use Cases
1.7 Business Objects
2) Analysis View
... Initial (or logical or conceptual or ... ) design views
3) Design View
... Technical Design Views
4) Implentation View
... Deployement etc

As well as this we give each modeller a "Work in Progress" view where they draft up the elements they are responsible for.

As each requirement solidifies it is moved into the Functional or Supplementary Requirements view.
Now depending on the system and users/SME's concerned, we gradually build up a set of packages under FR's and SR's that group the requirements into whatever is logical for the system, (note system not project) Typically, this might mimick the use case packiing structure but not necessarily.

What we aim to end up with, as we try to get them to use external rather than object requirements, is a repository of the formal requirments which is a sort of an "inventory"  These requirements are used in other diagrams throughout the d&d phases as linked elements, so they all have a common home and we can report, trace etc from a requirements viewpoint.

This is how we are proposing people use it - its obviously not the only way and it allows us to move people from legacy "heirarchical decompostion" thinking onto the UML world without too much brain strain.

hth
Bruce

[wmac]

Bruce

Thank you very much for your time. It is kind of you.

I like your structure. Except I prefer to have requirements and usecases in separate views.

By the way when I was working with Rational (I started RUP with it) tutor used to insist on a specific structure of views etc.

Then according RUP how much freedom we have in changing this structure. Are we completely free? (If we want to comply with RUP and UML standards).

I really appereciate your help and time you put here.

Regards,
Mac

[sargasso]

The major reason we are providing a structure is that we also provide virtual documents to go with it!

Each system team is free to adopt or adapt the structure as they feel fit - we encourage that.  (and its one of the GREAT things about EA that you can tailor the model structures - a thing that is not too easy or even impossible in other tools.

Glad to be able to help
Bruce