views:

168

answers:

2

I’m working on a project and have developed the high level user requirements for what the system must do. This project is a php mvc web application built on the CodeIgniter framework. Now I’m trying to take those requirements and break them down further into controllers/actions. What is the best way to do this?

I was thinking of creating a word document with a table that would have four columns. Column one would be the the name of the controller, column two would have the actions, column three would have the name of the view that is specific to the action, and the fourth column would show which users had access to that action. Does this sound like a good idea?

I like the interface first approach to building an application, but realistically, I need to know what views I need before I can create a prototype interface.

Could anyone help me out with how to plan the app and any documentation that might help?

+9  A: 

Your breakdown is a good idea, but it's really the second step.

here's what I'd do:

  • take your requirements, and turn them into a series of scenarios ("use cases", "user stories").

  • Pick one, and sketch, like on paper, the basics of the user interface you'd want if you were to have the Good Code Fairy deliver the perfect system to you.

  • separately go through the scenario, and underline all the nouns in the story; those are probably domain objects. Underline all the verbs in a different color. Each verb is a method of one of those domain objects. (In fact the domain object will be the object of the verb. Cool, huh?)

  • Figure out how you would implement that user interface using those domain objects.

  • Build it

  • Show it to your customer, who will invariably say "I like it but"

  • Put the changes and things you learned inot your requirements, and repeat until the check clears.

Peter Coad wrote what I still think is really the best beginners book on this: Java Design: Building Better Apps and Applets. It's oriented to Java, but the design part is universal.

Your domain objects are the model, the display of your data is (roughly speaking) the view, and the code attached to actions is the controller.


On Use Cases

The "right way" to do use cases or user stories is subject to immense discussion and religious warfare. There are zillions of options, from Cockburn's somewhat complex form, to notes scribbled on index cards.

For the kind of application you're describing, I do two things: I try to keep them to 25 words or less, and I think about the SMART acronym.

  • Twenty-five words or less helps keep them small. Doing a few small stories is preferable to spending weeks on a big one.

  • SMART stands for "Specific, Measurable, Agreement with Responsibilities and Tests." (Or at least that's how I interpret it. There are other versions.)

    • Specific, you have to be comfortable you know what's being asked.
    • Measurable, you have to have some way of testing or some kind of statement of what will be acceptable
    • Agreement, because it needs to be something you and the customer can both agree satisfies a need — in other words, the "meeting of minds" of a contract
    • with Responsibilities, you have to know what you're being given, what the customer or user is responsible for providing, and what you are
    • and Tests, in other words, you should have an effective procedure that gives you the answer "it is acceptable" or "it's not acceptable."

The form I use has the pattern

User in a particular role
does something
resulting in some benefit

So, in your example, I would write

  • Administrator (who?)
  • lists all FAQs (does what?)
  • to review them for updates. (why?)

The "resulting in some benefit" part is something I emphasize and a lot of other people don't, or don't even mention. It helps a lot later if you need to prioritize them.

The "test" part is a description of an acceptance test: you're answering the question "Is this done?" So the acceptance test might be

  • A logged in administrator selects "list FAQ". All known FAQs are listed in correct format.

Ideally, you'd set this up so some tool, like expect or a gui test tool, can run this automatically, but especially in a small projects you may end up testing by hand. You want automated testing, because as you build the system, you want to do regression tests; that is, you want to repeat your tests to make sure nothing has been broken by a later change.

Charlie Martin
Let's say I have a requirement of "Allow administrator to manage an FAQ."What use cases would I have for that requirement? Obviously to break down that requirement further, an Administrator would need to be able to add, edit, delete, view faq's. Would each of these have there own use case? or just the requirement as a whole?
Joe
Those are good questions, which is professor-speak for "I don't have a real definite answer." I'll add some more to the answer.
Charlie Martin
Thanks Charlie for your help. So if i'm understanding you correctly, each of those actions would have there own use case. What if the use case needs to be shared among different users. Say for instance, you have a blog controller, and an action on that controller might be edit_post. If you have multiple users writing blog posts, they would need access to the edit_post action, but a master admin might also need to edit a users post as well if he were reviewing posts. So you have two users needing to access the same function.
Joe
Yup. Now think object-oriented: if you have two kinds of users who both need the same kind operation, is one of them possibly a "kind of"the other? For example, an Administrator might be a kind of User; a User might be a kind of Person who has an Identity and a set of Permissions. The Identity might be what you build using the login process. And so on.
Charlie Martin
A: 

What you do is you work user-centered.

  1. You make rough mockups of the screens (use Balsamiq or something), and show them to your client/stakeholder, and walk them through it (as if they were using it). Get them to agree.
  2. Then you code the thing (I'm sure you can figure that part out)
  3. Then you show to your client again (have them actually use it in detail), and agree on changes.
  4. Now you finish it

Good luck!