One Way to Organize the Documentation for Wikis and Trackers in Agile

Scot Witt, Wednesday, March 5, 2008 @ 5:14 pm

One of the most difficult things I've had to get my arms around has been how you put user stories up on a wiki.

The books tell you to put 'em on cards with a number associated to the title. The idea being the developer and BA use the card to open conversation about a feature or function to draw out the requirements. And then, when the iteration is over, you throw the cards away.

Well, Blinkey, it doesn't appear to work when your client is 800 miles away. You have limited access to the Subject Matter Experts. The client wants docs for the business team. We've got nothing to show them but the specifications we're supposed to throw out. Don't make no sense, no how.

The Agilites (pretty good, eh?) usually say the BA comes in to run JAD sessions at the beginning of a project and the team never sees them again. Then the books suggest you bring the IA in with a designer 'when needed.'

PFD joins development with User Experience Design.

That means the IA and I (the BA) are permanently assigned to the team. So we do the documentation, run interference for the Dev and Business Teams and help everyone talk to everyone else.

Nice. But. The teams that have an active business team member empowered to make decisions are very lucky. We have built in delays on Q and A. And unless we politely remind the Business Team to concentrate on what's in the current  iteration, we can lose a great deal of productivity.

So. We've pulled some detail from fellow PFD'er Alice Toth and Agile Coach Dietrich Kappe and discussed between our Dev and Design Teams (the Design Team is me and the IA, marketing, it's all about marketing).

At the top level of the Wiki is the Release Master page. It contains the Iterations for that Release and links to each of the Iteration Pages.

The Iteration Pages have a live link to the Tracker application. Each item is linked. The items include the Tracking Issue (we use JIRA) and the Specification (User Story, work flow, business rules, wireframes and tests) for each Tracking Issue. Each Issue includes a cross reference link to the Specification and vice versa.

Pretty kewl, eh?

I sort of mashed the old specification form with Alice's User Story form (thanks again, Alice!).

• The Wiki Page Title is the User Story Title.
• Under the first header is the User Story. We've kept them to six sentences or less.
• Under the second header is workflow (task-flow for my UxD brothers and sisters).
• The third header is for Business Rules. If this goes over five, we start looking at splitting it up.
• The fourth header is the Wireframes. More than three and we start thinking about splitting the doc.
• The fifth is Tests. Two columns- one for action and one for expected result.

If we pour more than one User Story into the document, I'll place the test for each user story right under the User Story.

Advantages of this new system:

1. The docs are getting much closer to 'just enough' documentation.
2. The cross references are making it a lot easier for the developers since they're creating their technical documentation as they code and cross referencing everything in their browsers. In other words, it's easier for the developers.
3. Clearing out the crap lets the Design Team work ahead so we can have the developers read and research each Specification before the Iteration kickoff- we get better estimates and know when we have to go back to the client for more detail.
4. We know when the scope creeps- immediately.
5. The client has to approve before an item will be included in an iteration.

Disadvantages:

• Client confidence- for some reason the client wants the docs to dig a little deeper and be closer to Use Cases and complete functional specifications. So far, education seems to be mitigating this need.
• We made the shift in mid-iteration, so we still use a few old formatted specifications and the process isn't totally integrated yet- but this would be true of any change.

The key is the tests.

We hadn't included them until a month ago.

The Developers like them, as does the Design Team since it helps us all catch mistakes quickly and easily... if the design team missed specifying something, we revise before the specification ever leaves our browser.

And of course, Agile Development is test-directed development, we're getting closer and closer to that standard as well.

All in all, some fine changes.

tech development

Comments

• Leave a comment
• Comment feed for this post
• TrackBack URL

None so far.

Leave a comment