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?