Completing the User Story

Posted on September 13, 2014


What is Enough Documentation?

An Agile tenet is “just enough documentation” which people often take to mean no documentation, or just the information that is recorded in the card plus acceptance criteria, the rest to be filled in by conversation. In discussion about green field Agile utopias, this might be enough. In the real world, it is not.

Just the fact that most scrum teams employ Business Analysts to gather requirements shows that there is a body of work required beyond what is on the story card. So, what is enough? In our group we use an entire template to capture the work the analyst does. All together we might have 2-5 pages/story. This covers things like architecture, governance, dependencies, applicable personas, patterns, wireframes, etc. and we can cover these in detail at another time. Today I will talk about the least amount of work we do before tackling a story.

Definition of Begin

Our template helps us capture the information we consider the minimum detail for us to complete a technical design. In addition to well-crafted story and acceptance criteria, our “Definition of Begin” includes 3 parts:

– Wireframes that the team can walk through to cover the story

– Business rules for each Acceptance Criteria

– The test plan


Given that Agile is a user-centered methodology, it seems pretty obvious that we should have at least a sketch of the UI that shows the features we are developing. We develop these through a series of design sessions and refine them over the course of the current sprint for the upcoming sprint. You can use any tool you are comfortable with from paper sketches to Photoshop. We actually find a wireframe-specific tool like Balsamiq, with its “sketchy” style to be ideal because more polished tools like Photoshop give the impression of a “finished” design and people feel less freedom to change it. The whole point of having wireframes is to be fluid and make changes readily through the design process where change is much less expensive than it is in code. We don’t consider our design is ready until we can sit with the developers and walk through the story in a wire frame.

Business Rules, the Missing Piece

I have a rather crude but effective definition of acceptance criteria: something you can show the product owner on the screen/in a demo. This definition is simple and testable, but it is not sufficient to complete development. For example in our current sprint, working on a portal for a retail business, we pulled in a task list the story read like this:

As a manager, I want to see a list of completed tasks.

And the Acceptance Criteria are:

– Employee has ability to mark task as complete

– Tasks that are not completed by the end of day automatically move into an “expired” folder

– Ability for tasks to be assigned as daily, weekly, monthly, quarterly, semi-annually

That looks pretty straight forward, right? But there is a missing layer of specificity between the acceptance criteria and the technical design, and that is the business logic rules that the developer has to encode to handle triggers, exceptions, workflows, etc. During the wireframe discussions we pick up and document this layer of specificity between what is on the story card and what the developers really need to know to complete their technical design. For the above story we came up with the following rules.

a) Employee has ability to mark task as complete

b) Precondition= default view and no log in required, on the default landing page, and do not need to authenticate.

c) Marking as completed is anonymous

d) 3 different states for tasks: to do (active), completed, expired.

e) Incomplete  periodic tasks automatically move to the next time period (monthly to weekly, weekly to daily, etc). Incomplete daily tasks move into expired bucket

f) 4am-3:59am is 24 hour clock period

g) Expired task doesn’t get moved until end of the day.  Which is 3:59am.

h) Filter view for each time period: daily, weekly, monthly, semi-annual, annual

i) The default view of the expired bucket will show 30 days of expired tasks

With these simple clarifications, we’ve captured the meat of the conversations before we ever start development.

Test Cases are Hidden Requirements

There is one other thing that we’ve found invaluable in our goal for Zero Bug Sprints. We take these rules and have the QA team write the test plans from them before development ever starts. Think about it, what is the point of developers on one side of the room and “testers” on the other, both working on the same story and not communicating on how they will collaborate? Any test the code fails is essentially a hidden requirement the developer would’ve coded in had they known about it. Give the developers the test plan first and put the quality back in QA. This also helps break the “mini-waterfall” cycle where dev works for two weeks, hands the code to test in the last week, and then everybody scrambles to close the bugs before the three week sprint ends.

Definition of Done

One last thing you should do is document your code. In our template we document the pieces of the framework we implemented so that we can reuse or re-implement our patterns, and any technical debt we have so that we can close that out the next time we use the pattern. This is especially important to try to mitigate the steep curve for assimilating tribal knowledge in environments that use a rotating workforce of contractors.


Agile is about doing the right thing at the right time. That doesn’t necessarily mean less effort; but instead we hope to have less wasted effort. This includes documentation. We don’t do less documentation, we do the right documentation. Although our team actually includes a lot more documentation around our work than discussed here, these items are what we consider the minimum sufficient. You can do these few simple things today to inform your technical design, speed your development, and lower your bug count.

P.S. Who Are You and Where are You From?

Who is visiting me from the Ukraine?

WordPress gives me these awesome reports and I can see how people find me, where they live, how they found the blog, what pages they visited. I see people from Europe, Asia, South America, and I always wonder who they are. I would love to get comments from  you!

Posted in: Agile