Sign up ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free.

Little heads up, I'm the only lonely dev building/planning/mocking my project as I go. I've come up with a preview release that does only the core aspects of the system, with good business value, and I've coded most of the UI as dirty throw-able mockups over nicely abstracted and very minimal base code. In the end I know quite well what my clients want on the whole.

I can't take agile-ish cowboying anymore because I'm completely dis-organized and have no paper plan and since my clients are happy, things are getting more complex with more features and ideas. So I started using and learning Agile & Scrum

Here are my problems:

  1. I know what a functional spec is(sample): Do all user stories and/or scenarios become part of the functional spec?

  2. I know what user stories and tasks are.
    Are these kinda user stories? I don't see any Business Value reason added to them.

I made a mind map using freemind, I had problems like this:

Actor : Finance Manager >> Can Add a Financial Plan into the system because well that's the point of it?

What Business Value reason do I add for things like this?

Example : A user needs to be able to add a blog article (in the blogger app) because..?? It's the point of a blogger app, it centers around that feature?

How do I go into the finer details and system definitions:
Actor: Finance Manager >> Action: Adds a finance plan.

This adding is a complicated process with lots of steps.

What User Story will describe what a finance plan in the system is ??
I can add it into the functional spec under definitions explaining what a finance plan is and how one needs to add it into the system, but how do I get to the backlog planning from there?

Example: A Blog Article is mostly a textual document that can be written in rich text in the system. To add a blog article one must......

But how do you create backlog list/features out of this? Where are the user stories for what a blog article is and how one adds/removes it?

Finally, I'm a little confused about the relations between functional specs and user stories. Will my spec contain user stories in them with UI mockups?

Now will these user stories then branch out tasks which will make up something like a technical specification?

Example : EditorUser Can add a blog article.

  1. Use XML to store blog article.
  2. Add a form to add blog.
  3. Add Windows Live Writer Support.

That would be agile tasks but would that also be part of/or form the technical specs?

Some concrete examples/answers for my questions would be nice!!

share|improve this question

migrated from Jan 18 '11 at 20:31

This question came from our site for professional and enthusiast programmers.

closed as too broad by MichaelT, durron597, Snowman, Kilian Foth, gnat Jul 15 at 5:03

There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs.If this question can be reworded to fit the rules in the help center, please edit the question.

Update : One thing I learnt here is not to over think and engineer stuff. As I went coding I learn't more about the system and the requirements. –  gideon Mar 17 '11 at 13:33

2 Answers 2

up vote 6 down vote accepted

I think maybe you're getting too hung up on the documentation (ie: user stories and functional specs).

Your user story should describe some valuable feature of your software at its most basic. We use the standard user story phrasing - As a (actor), I need (some feature), so that (some value).

So, let's take this as an example:

Actor: Finance Manager >> Action: Adds a finance plan.

Now, without knowing what your app does or what your industry is, this might be wrong, but this is how I would write a user story for this:

As a Finance Manager, I need to add a Finance Plan to the system, so that I can better understand my clients' financial position*.

So, I've now got my user story and it describes what I need to do and why. This isn't the final word on the matter, user stories are simply a catalyst for starting a conversation. You can and absolutely SHOULD talk to your product owner and stakeholders about what this means. Now if, as a company, you have a shared understanding of what a "financial plan" is (ie, no one will stop and say "What's a financial plan?" when reading the story (unless they just need it clarified as it was previously called a 'money plan')) then there's really no need to write THAT up as a user story.

That said, however, you'll also need to back up the story with 'acceptance criteria' so you'll know when the story is donedonedone. There are many ways to write acceptance criteria and you'll need to find your own method of writing them, but you could use:

  • BDD (ie: scenarios (Given I am logged in, and I am on the first page of the financial plan adding form, and I enter 'my name' into the first name field, and I enter 'my last name' into the last name field, and I click the 'next' button, I should see 'step 2' of the form.))
  • Questions Can I enter all the relevant financial details into the form? Does the form check my social security number is correct? Does the form tell the user that there is a problem with their phone number?
  • Statements I can enter all the relevant financial details into the form. The form checks my social security number is correct. The form tells the user that there is a problem with their phone number
  • Referencing other documents (And this is where your question about where the financial plan is described) *The form is laid out as described in balsamiq mockup 0011_financial_plan.png. Each form field validates as described in functional_spec_financial_plan01.docx*

So, your user story describes some function needed and why it is needed. The acceptance criteria described how the business defines the story as done (how you define it as done is another matter) and now you have a starting point. You should pluck your card off the whiteboard (digital or otherwise) take it to your product owner/stake holder and say 'Got five minutes? Let's run through this to make sure we're on the same page.

I really can't stress enough that user stories are not contracts, they're not supposed to describe everything, they're just supposed to represent the work that needs doing and to help you collaborate on the same piece of work while using the story, written in plain English, to help you a) engage with your client and b) know when the story is done.

Hope this helps,


*(There's a method of decomposing stories to derive REAL value called the 'Five Whys', but I won't go into that here!)

share|improve this answer
+1 for "user stories are not contracts" –  Jeff Knecht Jan 19 '11 at 17:47

Here are some examples (slightly modified) of stories that I have written in the past:

  • The operations staff needs all warnings removed from the logs so that they don't get angry at developers when the disk fills up.

  • The data warehouse ingest program needs a consistent format in the log files so that it does not crash every other night.

  • The VP of Sales wants a mockup of the Monthly GL report so that item 7(c)4 can be checked off on the customer's contract.

The actors and the motivations in user stories are usually important clues about how the feature should be implemented. Ingest programs don't need pretty UI. The VP of Sales doesn't care about warnings in the log files.

Hopefully, your development team has a good enough understanding of their customer to avoid these silly mistakes, but sometimes the customer hasn't been clear. Or a new team member takes on a task without knowing important background information ("John hates orange!"). A well written user story helps us to remember those things.

share|improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.