Remove UI Details From Use Cases

by Admin 33 views
Remove UI Details from Use Cases

It looks like there's a bit of a recurring theme in our use cases (UCs) that needs addressing, guys. We're diving a little too deep into the specifics of the User Interface (UI), especially when it comes to stuff like confirmation messages, error messages, and the exact commands users input. This level of detail, while seemingly helpful, can actually make our documentation less flexible and harder to maintain in the long run.

The Problem: Overly Specific UI Details

In several use cases, we're spelling out the exact wording of messages and the precise format of commands. Let's break down why this is a problem:

  • Reduced Flexibility: When the UI changes (and it will change!), we have to go back and update all the use cases that reference those specific UI elements. This creates extra work and increases the risk of inconsistencies.
  • Focus on Implementation, Not Behavior: Use cases should describe what the system does, not how it does it. By focusing on UI details, we're blurring the line between requirements and design. We should be keeping that delineation precise and relevant to the case at hand.
  • Maintenance Nightmare: Imagine having to update dozens of use cases just because the wording of a confirmation message changed. Sounds like a drag, right? Let's avoid that situation.

Examples of Overly Specific Details

Let's look at some concrete examples from the original message to illustrate the issue. These are from UC01 and UC02, but similar issues are present elsewhere.

UC01: Delete Person

Under MSS (Main Success Scenario):

  1. ClubHub deletes the person from the system and all associated clubs, displaying a confirmation message: “Deleted person: [NAME]; Phone: [PHONE_NUMBER]; Email: [EMAIL]”; Address: [ADDRESS]; Tags: [TAGS].

This is too specific. We don't need to dictate the exact format of the confirmation message. A more general statement like "ClubHub confirms the person has been deleted, displaying relevant information" would be better.

Under Extensions:

3a1. ClubHub shows the message: “The person index provided is invalid”. Use case ends

Again, the exact wording isn't crucial. We could say, "ClubHub displays an error message indicating the person index is invalid."

3c1. ClubHub shows an error message: “Invalid command format! delete_person (deletep) : Deletes the person identified by the index number used in the displayed person list. Parameters: INDEX (must be a positive integer) Example: delete_person 1 ”.

This is overkill. The use case shouldn't specify the exact error message and command syntax. A more abstract description would suffice: "ClubHub displays an error message describing the correct command format."

UC02: Add Club

Under MSS:

  1. The user issues the command add_club n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS t/TAG1 t/TAG2 . Note that there can be any number of tags, including 0.

We don't need to specify the exact command syntax here. The use case should focus on the intent – that the user is providing the necessary information to create a new club. A better description would be: "The user provides the club's name, phone number, email address, address, and any relevant tags."

The Solution: Focus on the Essentials

The key is to focus on the essential behavior of the system, not the specific UI implementation. Here's a general approach we can take to revise the use cases:

  1. Identify UI-Specific Details: Go through each use case and highlight any instances where we're specifying the exact wording of messages, the precise format of commands, or other UI-related elements.
  2. Abstract the Description: Replace the specific details with more general descriptions of the system's behavior. For example, instead of "The system displays the message 'Invalid input,'" say "The system indicates that the input is invalid."
  3. Focus on the Goal: Make sure the use case clearly describes the user's goal and how the system helps them achieve it. The UI is just a means to an end; it shouldn't be the focus of the use case.
  4. Use Examples Wisely: If you feel it's necessary to provide examples of UI elements, do so in a separate section or appendix. This keeps the use case itself clean and focused on the core behavior.

Benefits of a More Abstract Approach

By removing unnecessary UI details from our use cases, we gain several advantages:

  • Increased Flexibility: Our documentation becomes more resilient to UI changes. We can update the UI without having to rewrite all of our use cases.
  • Improved Maintainability: Our use cases become easier to maintain and update. We can focus on the core behavior of the system, rather than getting bogged down in UI minutiae.
  • Clearer Requirements: By focusing on the what rather than the how, we create clearer and more concise requirements. This helps ensure that everyone understands what the system is supposed to do.
  • Better Communication: Abstract use cases are easier to understand and communicate to stakeholders, including developers, testers, and users.

How to Rewrite Use Cases: A Step-by-Step Guide

Okay, so how do we actually go about rewriting these use cases? Here’s a step-by-step guide to help you through the process:

Step 1: Review the Existing Use Case

Start by thoroughly reading the use case in question. Understand its purpose, the actors involved, the preconditions, the main success scenario, and any extensions or alternative flows. Identify all the parts that delve into specific UI details, such as exact command formats, message wording, or layout descriptions. Highlight these sections; they’re your targets for revision.

Step 2: Identify the Core Purpose

Ask yourself: What is the essential purpose of this use case? What is the user trying to achieve, and how does the system facilitate that? Strip away all the UI-specific language and focus on the underlying behavior. This will give you a solid foundation for rewriting the use case.

Step 3: Abstract the Language

Replace the specific UI details with more abstract language that describes the system’s behavior without dictating the implementation. Instead of saying “The system displays a message box with the text ‘Error: Invalid Input’”, say “The system notifies the user that the input is invalid.” This way, you’re conveying the same information without being tied to a particular UI element or wording.

Step 4: Focus on User Intent and System Response

Frame the use case in terms of the user's intent and the system's response. What action does the user take, and how does the system react to that action? This will help you keep the focus on the core behavior rather than the UI. For example, instead of “The user enters the command ‘delete_person 123’”, say “The user requests to delete person with ID 123.”

Step 5: Separate UI Examples (If Necessary)

If you feel it’s important to provide examples of UI elements or interactions, do so in a separate section or appendix. This keeps the main use case clean and focused on the essential behavior. You can include screenshots, mockups, or sample code snippets in this separate section, but make sure they are clearly labeled as examples and not considered part of the core requirements.

Step 6: Review and Refine

Once you’ve rewritten the use case, review it carefully to ensure that it is clear, concise, and focused on the essential behavior. Ask yourself: Is this use case easy to understand? Does it accurately describe the system’s behavior without getting bogged down in UI details? If not, refine your language until it meets these criteria. It can be helpful to have someone else review your work as well, to get a fresh perspective.

Examples of Rewritten Use Case Steps

To illustrate how this works in practice, let’s take a look at a few examples of rewritten use case steps:

Original (Too Specific):

The system displays a confirmation message: “Person deleted successfully. ID: 123, Name: John Doe”.

Rewritten (More Abstract):

The system confirms that the person has been successfully deleted, displaying relevant details such as their ID and name.

Original (Too Specific):

The user enters the command “add_club name=ChessClub location=RoomA”.

Rewritten (More Abstract):

The user provides the necessary information to create a new club, including its name and location.

Original (Too Specific):

The system shows an error message: “Invalid date format. Please use YYYY-MM-DD”.

Rewritten (More Abstract):

The system informs the user that the date format is invalid and indicates the expected format.

Conclusion

By focusing on the essential behavior of the system and avoiding unnecessary UI details, we can create use cases that are more flexible, maintainable, and easier to understand. This will ultimately lead to better communication, clearer requirements, and a more successful development process. So, let's make a conscious effort to abstract our use cases and focus on the what, not the how. Our future selves will thank us for it!