How to document an interactive/brochure website?

[kelly_sumrall]

I want to capture requirements for a new web project. This seems to be so basic, that I am a little embarrassed to be asking for advice, but, I want to get it right and show my colleagues in the office how good documentation can help a project. That being said, here is my situation.

I’m building a web site that is presented to three different user groups: Public User, Member User, and Administrative User. Here is a simple UC diagram. What are the thoughts of the forum members? I'm open to any critisism, as long as it is educational.

I think this is a common scenario and could be used as a “real world pattern” example on the wiki.



Use Cases...

[size=16]Browse Public Pages[/size]
User performs UC: Navigate to HomePage.
User requests a public page.
System displays the page.

[size=16]Create an Account[/size]
User makes a request to create a new account.
System displays Account Credentials setup page (username/password).
User supplies unique username and password.
System displays the profile page.
User fills in form fields.
[User submits form.]
System creates user account.
System displays the Logged In Homepage.

Alt:
Username is not unique.
At [User submits form.], System determines the username is not unique.
System creates suggestions.
System displays Account Credentials setup page with message indicating the user must enter a different username and offers suggestions.
[User submits form.]

Password does not match requirements.
At [User submits form.], System determines the password does not meet the requirements.
System displays Account Credentials stup page with message indicating the problem with the password.
[User submits form.]

[size=16]Browse Member Pages[/size]
[User requests a member page.]
System determines the user is logged in.
System displays the member page.

Alt:
User is not logged in.
At [User requests a member page.], System determines the user is not logged in. (This can happen if the request is coming from a bookmark or by typing the url directly.)
System performs UC: Log In

[size=16]Browse Administrative Pages[/size]
[User requests an administrative page.]
System determines the user is logged in.
System determines the user is a member of the administrative group.
System displays the administrative page.

Alt:
User is not logged in.
At [User requests an administrative page.], System determines the user is not logged in.
System performs UC: Log In

User is not a member of the administrative group.
System displays an error page with a message indicating the user is trying to access a protected page and they do not have permission.

[size=16]Log In[/size]
User makes a request to log in.
System displays the login page.
[User fills in the form.]
[User submits the form.]
System verifies account information.
[System displays member page.]

Alt:
Invalid Credentials
At [User submits the form.], System determines there is no account matching the submitted information.
System displays the login page with a message indicating the username or password is incorrect.

Login request comes from a redirect.
At [System displays member page.], system determines the login request came from an attempt to view a member page by a non logged in user.
System displays the originally requested member page.

[size=16]Navigate to HomePage[/size]
[User navigates to the HomePage.]
System determines the user is not logged in.
System displays the public page.

Alt:
User is logged in.
After [User navigates to the HomePage.], System determines User is logged in.
System determines User is not a member of the administrative group.
System displays Member HomePage.

User is logged in and member of administrative group.
After [User navigates to the HomePage.], System determines User is logged in.
System determines User is a member of the administrative group.
System displays Administrative HomePage.

[sargasso]

Since you have asked for opinion  

1. You have described the system, not the requirements.
2. The only use case I can see in the model is "Create an account".  No other, IMO,  has any true value to the (initiatiing) actor.
3. Since the other two actors are specializations of Public User, there is no need to show them using communicating with use cases that are linked to the public member.
4. Why would a LoggedInUser invoke the LogIn "use case".  This seems to imply that you hae to be LoggedIn before you can LogIn  (BTW IMNVHO Log In is never a use case - no one will pay me to sit around a terminal and perform 200 log ins a day).  

[kelly_sumrall]

Bruce,

Thanks for the reply. If these interactions don't qualify as use cases (and I'm not arguing that they do), how do you go about documenting the behavior and requirements of something like this? I treated each one as a use case, and while creating the scenarios, I actually discovered some alternate behaviors that my colleagues and I didn't think about during the initial brainstorming. How would you recommend documenting something like this so that the client could understand? It took us a couple of hours to get to a point where we all started envisioning  the same pattern, beforehand, we all had our own individual idea of how the site would function for the various user groups.

4. Why would a LoggedInUser invoke the LogIn "use case".  This seems to imply that you hae to be LoggedIn before you can LogIn

Good catch. It always helps to have another set of eyes.

This forum is my only link to people with the skill and experience of documenting requirements I have (can't communicate with a book), so please be liberal with suggestions.

Kelly

[kelly_sumrall]

Bruce,

I've thinking about your opinion on Logging In never being a use case. That makes sense to me if it is at least a step in a more general use case. If that is the case, how do you go about documenting the log in requirements, such as using a userid/password combo or windows authentication?

[KP]

Why would a LoggedInUser invoke the LogIn "use case".  This seems to imply that you hae to be LoggedIn before you can LogIn  

I think a better name than LoggedInUser is needed. The OP mentions "MemberUser"; "RegisteredUser" would be my choice.

The only use case I can see in the model is "Create an account".  No other, IMO,  has any true value to the (initiatiing) actor.

Slightly disagree: for a brochure website "Browse Public Pages" can be a goal for PublicUser. That's 90% of what I do on the web!

[sargasso]

KP:

That's 90% of what I do on the web!

Iwould have thought that 90% of what you do on the web is "obtain great ideas from Sparx forum people" (45%) and "understand EA user disatisfaction with the UI" (45%).  

TBS these are examples of the types of things I model for web sites.  Why should/do people use (commercial) web sites?  Hopefully, a) ObtainProductInformation and b)PurchaseGoodsAndServices.  Augmented, perhaps, with c) CommunicateWithSupplier, d)ObtainSupportInformation.  While these may at first glance apear to be user goals, its just cause I write that way.

Look at the Sparx site.  All four of these "core" use cases are supported, directly and separately.  (N.B. I can do each of them without extends or includes.)

Now there are some more use cases available from the Sparx website that may be of interest in specific types of sites and not to others.  "AccessPrivilegedInfo" (registered users, and "CommunicateWithOtherUsers" ....  for example.

These are the types of things you (kelly) should be discussing with the users - not how it will be implemented. Or at least not until you have got a good agreement of the scope of the site.  Are there other sites in your industry you could refer to as models or prototypes, explaining to the users "well here are some use cases supported by competitor/other organizations, should our site include such things?"  

Finally, IMO/IME existent business rules and existent users are the worst possible providers of ecommerce business flow models for web sites - use ay means possible to get ahold of tame customers and ask them how they want to interact with the company over the web.  Depending on the product, the boss's spouses are the pre-eminent choice.

hth
bruce

p.s.  getting back to log in,  until a client convinces me that  they understand the (if there is one)  real benefit obtained from a log in use case I will fight for its exclusion from every model I come in contact with, be it a web system or an internal system.  At best its a step in an activity flow, at worst its an outright waste of time and money.

"But if I dont specify it, the coders wont know that they need to do it" --- [size=48]B.S.[/size]  Put a single line in the constraints section of relevant use cases saying "this use case can only be initiated by users who have previously obtained a session cookie via the company standard web login method".  If the coders dont know what that is, kill them.  If the company IT artchitects have not specified the company standard web log in mechanism, kill them.  It'll save you time and tears on your project I can tell you.

p.p.s.  While I'm in this rave mode...
Consider the core Sparx use cases, each one of them could be provided as the single use case for a viable web site of this type.  Such a site would still be of value to both Sparx and the user.  Now how about a web site that all it did was provide a "log in" use case - is that viable?  Well, here it is - try it out.http://sargasso.sphosting.com/LIIndex.htm (ID="x", pwd="y")

[jeshaw2]

With regard to the Login Use Case:  I think the point of such a requirement is being missed here.  

Business systems normally have a Requirement to be Secure and this requirement needs to be modeled in the CIM & PIM.  However, unlike the general business functions supported by software, security is an aspect that cuts across those business operations.

Except perhaps for a Security Administrator, security is not a goal described by a use case.  In reality, security is a statement of policy of who may do what to/with system resources.  Describing a need to "login" does not adequately describe the distribution of power and authority across the various functions of a business system.

Security is better described as a hierarchy of Business Policy Objects (modeling the underlying business rules)   and /or interface design.  "Loging in" is an implementation level issue that specifies only one of many possible ways of implementing security.

[Jan ´Bary´ Glas]

With regard to the Login Use Case:  I think the point of such a requirement is being missed here.  

Business systems normally have a Requirement to be Secure and this requirement needs to be modeled in the CIM & PIM.  However, unlike the general business functions supported by software, security is an aspect that cuts across those business operations.

Except perhaps for a Security Administrator, security is not a goal described by a use case.  In reality, security is a statement of policy of who may do what to/with system resources.  Describing a need to "login" does not adequately describe the distribution of power and authority across the various functions of a business system.

Security is better described as a hierarchy of Business Policy Objects (modeling the underlying business rules)   and /or interface design.  "Loging in" is an implementation level issue that specifies only one of many possible ways of implementing security.

No comment. That's it. Read everyone. Tell everyone. Believe in it.

[kelly_sumrall]

I am starting to see the error of my ways here. I'm new to the process of documenting requirements and have somehow gotten stuck with trying to put everything in a use case. That does not work. I need to learn how to determine what warrants its own use case and what just needs to be recorded as a requirement.
For example, if a site has secure sections that require authentication, how do you go about documenting the login requirements in a Word, or in EA? If the pages are secured via account permissions, the browser can handle all the login details for you, such as browsing a corporate intranet with IE. If the site uses a user id/password lookup login mechanism, that will require substantially more requirements documentation to answer questions about how errors are displayed, should you prevent login attempts after so many tries, etc.
Where/how do you document (or store in EA) these types of requirements so that the client can accept them and sign off on them?

[jeshaw2]

Kelly;
The EAExample project is distributed with EA.  Open that project and look at the Requirements Model views.