DougHughes.net

This entry is a continuation of my series on learning the UML. This entry follows up on my recent entry on Use Case Diagrams.

Shortly after posting my entry on Use Case diagrams I received an email from Doug Keen saying that I might have gotten a few things wrong. I expected this. He made some interesting point and I went and read some more on Use Case Diagrams.

Doug’s criticism was primarily that I show too much “sequence” in the Use Case diagrams I wrote. After considering this and reading more I think he might be right.

I noted in my last entry that when I wrote my requirements document that I had some preconceived notions which made it into the requirements document. These preconceived notions were mostly functional in nature. For instance, I listed a number of “users” of the Search API I’m designing:

• Search User
• Queue Manager
• Content Retriever
• Content Inspector
• Index Manager

Before writing my blog entry on requirements gathering and use case diagrams, I had been reading about use case diagrams and thinking about what would appear in one for my search API. After thinking for several days I went back and wrote my requirements document. However, I don’t think I did a very good job actually defining requirements.

Consider this: Why am I placing design-related information in my requirements document?

In my entry on requirements gathering I state that the resulting document focuses on the following items:

• The business process which will be modeled by the application
• The user and systems which will use and interact the new application
• The resources which the system depends on and creates
• The functionality of the system as related to the first three items.

Considering those bullet points, where does “Queue Manager” fit it?

I thought that the Queue Manager was a user although I knew it was part of the system. In the end I think this might be wrong. By defining the Queue Manager (and other system users) during the requirements gathering phase, I boxed myself into a particular design before even beginning the design process.

This might mean that my API only has two users:

• The user which invokes the indexing process
  • I’ll call this the Index Invoker, for lack of a better name
• The user who searches for content
  • I’ll call this the Search User.

This makes since. I’m not really designing a system, I’m designing an API. The API is a small set of functionality which will be integrated into a larger system.

At the moment I don’t have time to update my requirements document. I’ll do it as soon as I can.

By changing the users, I change the structure of my Use Case diagrams. I think that my Search Index Use Case Diagram might end up being as simple as this:

This very eloquently describes the functionality the Search User will use.

The Index Content Use Case diagram might look like this:

This new version does a pretty good job of explaining the system from the user perspective.

What do you think? Do we need to revisit this again?