5

I have this requirement:

The application must allow the Administrator to edit, create and delete Users.

Now, I have heard that each action must go in a functional requirement, and my question is: What of the following statements would be the more appropriate(if any):

1:

The application must allow the Administrator to edit, create and delete Users.

2:

The application must allow the Administrator to edit Users.
The application must allow the Administrator to create Users.
The application must allow the Administrator to delete Users.
rendon
  • 171
  • 1
  • 6

4 Answers4

7

I would go for number two.

Functions in function definitions while they should be worded in business terms should be atomic. What I mean by that is "maintain customer data" could include add, edit, delete, archive, disable etc. etc. A in list of functions "delete the customer data" could mean only one thing.

This helps specify the system more exactly in discussion with users as they are liable to say things like "I didn't mean remove the customer form the file, I meant flag him as an ex-customer", which they might have felt was an obvious implication of "maintain customer data".

James Anderson
  • 18,147
  • 1
  • 43
  • 72
6

Your answer is the second option. Creating, editing and deleting are different actions, so you must have each of them explicitly stated.

Consider that a new user type comes into play, Moderator. A new requirement arises, Moderators can create users but cannot edit or delete. Now if you wrote your first requirement specification as:

The application must allow the Administrator to edit, create and delete Users.

and your second requirement as:

Moderators can create users.

it looks like they are seperate functionalities. But in your second option you can easily observe that Administrator and Moderator shares a common functionality "Creating" users.

Mert Akcakaya
  • 2,099
  • 1
  • 13
  • 16
2

It would definitely be 2. But it should contain more.

In general, write the minimum line you can think of - and then break it.

For example

  • Administrator should be able to add a User.

Looks good? You have to gather much more requirements.

  • Define what a "User" is, i.e. the attributes of user ( name, address, picture, etc.. ).
  • Define which ones are mandatory ( name?, tel-no? ) and required while adding

Then ask more questions

  • Do I need First, Last and Middle. Are all of them necessary?
  • Do I need Area code for Tel-no? International code? which ones are mandatory?

You can keep asking questions about the application and come up with more granular specifications. Don't assume anything.

You get the general idea.

Chip
  • 322
  • Also: what happens if a user is deleted? What if the user has content assigned to it? What happens to the content? – Joachim Sauer May 18 '12 at 09:33
  • @JoachimSauer Absolutely, I just gave an example for deepening questions on "add". There are a lot of questions on edit and delete. – Chip May 18 '12 at 22:06
0

First is better.

It's more concise and equally clear.

A functional requirement is a way of communicating to others what the software needs to do. If you are treating it like a checklist or a legal document where everything must be laid out in laborious detail, then you are doing it wrong IMHO.

Even better would be to leave the requirement at a higher level:

Administrators must be able to manage the list of users

It is then up to the team to determine the best way to implement this. This might involve editing, creating and deleting users. But it might equally include bulk upload or some other features that you didn't think about in your initial functional requirements and might need to be developed over a couple of iterations with real users.

mikera
  • 20,707
  • 1
    Manage is a very vague term. I would avoid it in functional requirements. For example - can an administrator "sort" the list? – Chip May 18 '12 at 07:52
  • @Chip - maybe you need sorting, maybe not. The point is that you probably don't know until you've actually built something, shown it to users, tried it with some real data and understood how they are going to use it. There isn't much point specifying in great detail before then. Of course, I'm assuming a relatively agile development model here. If you like BDUF then go wild with your specs, just don't come complaining to me when it costs a fortune and goes years over budget :-) – mikera May 18 '12 at 07:59
  • You are absolutely right. What you are talking about is agile ( which I love ). But you don't have functional specs in agile do you? – Chip May 18 '12 at 08:06
  • Also, you are absolutely right that you don't know what you want. But you should communicate clearly what you are assuming - for example you are going for add, edit and delete. That's your assumption. That's what you are going to do. "Manage" doesn't mean anything. – Chip May 18 '12 at 08:08
  • 1
    I'd argue that you do have functional specs in Agile - they are just more frequently called user stories. I'd be perfectly happy if one of my teams wrote on an initial story card: "As an administrator I want to manage the list of users so that I can ensure the right users have access to the system". Manage is indeed a general word but I think it is justified here in the sense that it means "to control in order to meet an objective" - i.e. I think it would be understood by a reasonably intelligent reader in this context. – mikera May 18 '12 at 09:40
  • The story wouldn't stop with just "manage the list of users" but would also include a bulleted list detailing what this means, as well as additional clarifying discussion (for example, on the back of the card) to help clarify the requirement as new information is uncovered, and maybe even some paper prototypes showing what the feature would look like. – Michael May 21 '12 at 19:03