Along with design sketches and requirements, as part of the concurrent design and requirements development for our agile project, we have created a UML class diagram representing the domain. This iterative process allows us to incorporate the benefits of each perspective rapidly with the others in our race to prototype a working site.
This article reviews the domain model.
UML Class Diagram Background
Scott Ambler has an excellent article explaining how to use and read UML 2.0 Class Diagrams – also called static diagrams or static models. This article does not have the typical “explain how to read it” introduction, please bear with me, or refer to Scott Ambler’s excellent tutorial as background for this. [Note: Ambler will have a lot of articles submitted to the ratings site – he does lots of great stuff!]
Ratings Project UML Class Diagram
The goal of this diagram is to capture / describe our understanding of the space – an object oriented analysis step. This diagram represents a business-perspective on the space, not an implementation-perspective. The implementation will look very similar, and does crop up a little in the naming of attributes. In “true agile fashion” we are trying to use the same document to represent the OOA as well as OOD artifacts.
[larger]
This is the 20070424 version of the model. It will evolve. If you see any glaring holes or errors, please mention them in the discussion below this article.
[Update 20070427. Here’s the next version of the domain model]
Ratings Project Domain Entities
Article
- articleScore. Each article will have a score that represents the collective perception of the quality of the article.
- articleReviews. A list of all reviews / commentary on the article.
- articleSubmitter. The user who submitted the article.
- articleTimestamp. When the article was submitted.
- articleRatings. [Private]. The individual ratings of the article, used to calculate the score.
- articleStatus. [Private]. An article can be public, possibly private, or removed (no longer visible to users, but still in the database to prevent its re-appearance).
User
- userRatings. All of the ratings submitted by the user.
- userArticles. All of the articles submitted by the user.
- userAdmiredUsers. Possibly have a list of users who you admire. Keeping this as a placeholder.
- userFans. Possibly have a list of all users who admire you. Placeholder.
- userRole. [Private?] A user can be an admin, can submit articles, and can review articles. Most likely, anyone who can review can submit. An admin can do both, but also has the ability to “clean house” in the system.
- userContactRule. [Private?] A user may allow other users to contact her. The site may provide an abstraction/email interface that allows contact without revealing email addresses. And people may want to restrict who can contact them based on the fan-admired network, or allow any user to contact them. Another placeholder for future possibilities.
Rating
- ratingArticle. The article being rated.
- ratingUser. The user doing the rating.
- ratingValue. The actual rating value assigned to the article by the user.
- ratingTimestamp. When the rating was created.
Review
- reviewArticle. The article being reviewed.
- reviewUser. The user doing the reviewing.
- reviewTimestamp. When the review was created.
- reviewTitle. Title of the review (e.g. “Best. Article. Ever.”)
- reviewBody. The content of the review. Possibly “safe” html, analogous to comment field limitations on blogs.
Thoughts And Questions
- User metadata (name, loginID, pwd, email, timestamp, etc) is missing from the domain model. Pwd will need to be encrypted in the database [design note: probably SHA1 vs. MD5 – review details and options to determine].
- Should user roles be private?
- Is there a reason to have a distinction between reviewers and submitters? What would be the reason that someone would be able to do one, but not the other?
- Any contact rules other than “Only people I admire”, “People I admire or who admire me”, “All registered users”, and “No One?”
- ratingValue – last night, I believe I convinced myself not to do it this way. Will cover in more detail in the next article.
- Should people be able to “Rate” a review? Think of Amazon’s “Was this review helpfull?” feature. Over time, the feedback that people give to reviewers could be used to create a notion of credibility, or be used to determine similarity of opinion between users.
- What about threaded commenting? Essentially reviews of reviews – not just reviews of articles.
Share your thoughts and feedback below. And thanks in advance.
It’s not agile to get hung up on the format of documentation, but I would look into Craig Larman’s thoughts on domain/conceptual models. In particular, you might err more on the side of including a greater number of full-fledged concepts instead of attributes:
“Perhaps the most common mistake when creating a conceptual model is to represent something as an attribute when it should have been a concept.”
Larman offers a guideline:
“If we do not think of some concept X as a number or text in the real world, X is probably a concept, not an attribute.”
However:
“If in doubt, make it a separate concept.”
This information comes from Larman’s APPLYING UML AND PATTERNS.
A submitted (rated, reviewed) article could be changed by its author, hopefully turning it into an even better article. Should the author resubmit it? Leave a comment?
How about a link-last-checked timestamp? Checking can be done automatically, I guess.
reviewTitle and reviewBody:
It should be possible to fill in the Title only (for short comments)
User metadata: Isn’t there a technology that relieves me of entering my data in dozends of sites?
Should user roles be private? No.
Is there a reason to have a distinction between reviewers and submitters? No.
Any other contact rules? I can’t see the point in having contact rules. Please explain.
Should people be able to “Rate†a review? Yes!
Threaded commenting? I think rating reviews is enough.
Hey Roger,
I take your comment as a great suggestion, not a “form of documentation” critique! You’re making a suggestion about representation of the domain model – not description. I’ll have to check out Larman’s book, but I was generally trying to follow exactly that precept.
Example: Rating is a first class object, not just an attribute. The enumerations are another manifestation of this. I realize the blog-documentation approach makes it harder to consume (because I included the easily scannable attribute-placeholders).
With the diagram, I tried to show all of the relationships as concepts – including multiplicity and navigability intentionally. As a habit in previous OOA/OOD efforts, I started “double documenting” each relationship as an attribute name (userRatings is an example) to make the document easier to scan over time – reminding me that there is a relationship there.
Maybe Larman has a better approach to describing the concepts, I’ll have to check. Thanks again for the suggestion – and I will definitely turn up the volume on that as I move forward.
And thanks again for your sustained readership and multiple contributions to discussions basically since the beginning of the blog. I truly appreciate it.
Roger – I forgot to ask – is there a specific example in this diagram where I could have represented something better? That would help me understand and improve more quickly.
TIA
Hey Rolf, thanks again for the tons of input!
Edit/resubmit: I think the rule we need to use is “only if the URL changes, should the author resubmit.” I would encourage Brian (the Blogger persona) to add a review of an existing article when he edits it.
Link-last-checked. Cool idea. I put it in “surprise and delight”, but it’s on the stack.
login – I use, and would love to support openID user authentication. Will have to add that. Not sure what’s already been done with Rails to support it. openID allows exactly what you suggest.
Contact-rules: From a community standpoint, people may want to send private emails to each other. But they won’t want to share their email addresses publicly on the site. I think we should be able to facilitate sending emails opaquely from one user to another. Would likely be a minor extension to the support we need for Paul’s (the product manager persona) broadcast of articles to non-users by email. But if people anticipate getting spammed with emails from “non-qualified” other users, they may use a secondary email address (like spam@hotmail.com) and never see the “real” emails. Or even worse, not sign up. This was a design attempt to address an implicit requirement for community participation.
Rating of reviews – got it.
Thanks again!
Contact-rules: I see. Good thing.
Scott, you asked for a specific example. I actually hadn’t studied the diagram closely enough to realize you were “double documenting” the concepts as attributes. Overall, the diagram feels a bit “implementationish”, but I don’t really have an example. Maybe it’s just that attributes feel like implementation to me. The more I study the diagram, though, the better it looks to me.
Thanks Roger!
Yeah, it is a little implementationish. Probably because I’m going to be doing the implementing, so adding some extra stuff/thoughts into it “while I’m there” is a risk.
Thanks for taking the time to look at the diagram in more detail, and reply.