Going from requirements to use cases and how to know if my document is good enough

Question

I'm here again asking about software documentation. I read a lot about it but it is a bit harder to put in practice, first because of the lack of examples and second because most small companies just don't care at all.

So I have a set of requirements for functionalities for a iteration of a software that I and a friend is doing. see bellow:

• The system shall enable users to login through a UI* where he enters a username* and password*.
• The system shall display an error message on a particular area of ​​the UI* If the user* enters a combination of wrong username and password.
• The system shall redirect the user to a welcome UI* after successfully logged in.
• The system shall allow each user to have an access level, forming a hierarchy where only users of higher levels can perform an action* on users* from lower levels.
• The system shall associate users* that have special permissions* for a custom group*.
• The system shall associate each user* with a group*.
• The system shall retain the permissions* per user if the user belongs to the custom group*. Otherwise the permissions* should be inherited from the group.
• The system shall enable password reset only generating an automatic password and sending to the user's* email.
• The system must store the following user information, login, group, password, name, email, mobile phone.
• The system should allow users to change their information.
• The system should enable administration of permissions* actions*, groups* and users* through a UI* where user's can add, delete, create and edit entries (eg. Add groups, delete users).

So should I challenge these requirements more? How can I test/challenge it effectively?

After that, how can I go from this set of requirements to use cases (assuming they are good enough) to Use case.

I know I need to start finding the actors. But the only actor I see is the 'user' and he will performing CRUD operations on users, actions, groups and permissions. But how should I detail these use cases, 'Manage users' for example? Or should I go for a deeper detail level? Like 'add user' 'create group', etc.

glossary
*user: is the person who will use the system to manage it based on his privileges.
*UI: user interface.
*username: a set of characters with max length of 50 with alpha numeric chars.
*password: a set of characters with max length of 50 with alpha numeric chars, must be encrypted.
*group: a list of named groups that each user must be associated with.
*actions: a list of actions a user can do on the system that must be associated with permissions.
*permission: a list associating users and groups to a specific action.

Thank you guys.

Answer 1

One of the challenges you may have is that you approach writing requirements and writing use cases somewhat differently, so it can be hard to simply take one and go to the other.

First, on the requirements, my feeling is that you've taken them far enough short of providing more technical details like table diagrams and things. Since those seems solid, I won't dig into them too much.

On use cases or user stories, to find the actors, you want to look at who wants to do what. The user wants to be authenticated, change his password, etc. Even the security things you've got in there should be driven by the user's desire to keep their account secure. If there are backend user management features, who does those? Maybe it's a CSR or account manager and that's probably the actor in your use case. If you can't find an actor, you want to ask yourself if this is something someone really wants or if it's something people are just used to seeing. Understanding who wants it and why is important because....

Writing use cases and requirements usually get you different lists. I prefer use cases or user stories (there are some formatting differences, but their goal is the same) because it's easier to get the right stuff in, especially in iterative development. For example, if you take a use-case perspective on logging in, you find that the user doesn't actually want to log in. He wants you to only show his info to him. That means you need some sort of authentication token. Your cases look more like this:

• As a user, I would like my information to be shown only if the session is authenticated as me so other people can't see my data.
• As a user, I'd like to be able to authenticate my session so the system know's it's me.

There are two interesting things about this. First, it is apparent that I actually don't need to do the authentication process first. If I'm only releasing to a very small group or internally for the time, it might not be worth all of the time to create a big login interface if I have a simpler way of creating an authenticated session for now - the rest can come later. Secondly, by building my application in this order using SOLID principles, I leave my authentication open to any kind of login I decide on later. This means I can do a custom login, SSO, kerberos tickets, or whatever. It gives me a lot of options down the line if I understand what the user needs are instead of trying to base my use cases off of requirements.

This is a tough topic, so I hope this helps. Done right, good use cases can lead to amazing applications.

Answer 2

The estimation phase is a good way to test whether your use cases are good enough. In that phase estimators (it is best if there are more than one) will put a rough estimate to the user story or requirement. Two things determine if you need to add detail or further break up requirements:

1. If the estimators cannot estimate because there are too many unknowns then you will need to add more detail.
2. If the estimators come up with a huge estimate then that means the requirement is too broad and needs to be split apart into components.

User stories are a good way to format requirements so that they tell what needs to be created and why. This will solve your use case question and will make it so you don't have to tiie use cases back to specific requirements because they will be one and the same.

The format for a user story is: As a {role}, I want {task to perform} so that I can {achieve some goal/benefit/value}

User stories also help with prioritization because they implicitly explain the goal and the value to the user.

I wrote a blog article about this phase of early design that explains about setting goals, requirements and constraints before getting into the creative part of design. I use unconventional design figures to help explain the process. "Design like Einstein and Michelangelo" https://medium.com/@dave.b.kaplan/design-like-einstein-and-michelangelo-fadf2c86e3f7