Brad Storm’s Lofty Thoughts

So, there you are, the iteration is on and you get assigned / choose a task for you to do. Some project manager has decided what tasks should fill this iteration and it’s up to you, the developer, to come through with a solution. As a developer you have to relate to several parameters:

• What’s the time frame for this task?
• What is this task really about (details and purpose)?
• How does this task fit into the big picture (the application as a whole)?

To answer these questions, agile development introduce the DOMAIN WALKTHROUGH

A domain walkthrough is all about understanding the problem domain. The essence of the solution. A domain walkthrough is held together with someone who understands the domain well and (important!) is one of the decision makers in the process (refered to as “the customer”). It’s important that they can explain their intentions to you, the developer, and that you can ask the right questions and maybe even give recommendations for better solutions than what they had imagined. Depending on how the project team is assembled, there should be a project manager or product owner present to do make sure whatever is said and agreed upon is part of the original contract .

The time frame and the existing understanding of the domain area will determine the need for the domain walkthrough. If the task is set for four hours to edit an already existing feature, no more than a single phone call might be needed. A two-week task about a new domain calls for a more extensive domain walkthrough face to face with maybe the customer experts as well.

Doing the domain walkthrough

The main idea with the DW is to get a common understanding of what will be solved: the developer understands the purpose of the task better, while the customer gets a better picture what awaits when the task is solved.

The first thing is to get a metaphor in place. This is short description, no longer than a few lines, explaining the main purpose of the task (see XP). From this point on a DW could process like a flow chart:

• where’s the entry point to the task?
• What information is required to perform the task?
• What input is needed during the task?
• What steps must be taken to complete the task?
• What conditions apply?
• What restrictions apply?
• Are there any specific business rules present?
• In which way should the outcome be presented?

There might surface a lot of details through such a meeting. This is good, since they will most likely come back and haunt you if you didn’t catch them up front. Again, make sure that these details are well within the contract boundaries. But how do you keep track of all these details?

User stories

Every thing that the customer express that has relevance to the task must be documented. A way to do this is through user stories. A user story is simply some text describing a condition, restriction, definition or rule about the domain. The key thing is to write the user story in whole sentences. For instance:

“Calculate expenses” is not a very good user story, but “the booking review should calculate the customers expenses before confirming the order” is alot better. A whole sentence describes who’s doing what to where/who. By writing a user story like this, new question arise: “What expenses are included in this calculation?”. This leads to another definition of what “expenses” mean in this instance.

Another user story: “the booking process should store the customers order history for future reference” is detailed enough. It could be written :”the system should store order history”, which is not very good since a “system” or “order history” isn’t very accurate. In fact, try to avoid using words as “system” or “database” or “code” or other technical terms in a user story. Stick to words that express business logic. In fact, the best way to force this is to let the customer write the user stories!

Another good practice is to draw the relationship between the user stories on a map through something like a flow chart. But by labeling each node with a business related name, it’s easier to understand the bigger picture. This is referred to as Domain Modelling. It’s useful to stick with this map for future reference and use it as a living document.

When going through the domain model, a developer should always keep the simplest solution in mind. If the process can be simplified at any point, any steps can be shortened or any requirements made easier, it should be brought up and adressed to the customer. To negotiate a simple solution at this stage might save houndreds of development and testing hours later on.

You don’t need any high-tech tools to use user stories or domain modelling. In fact, smaller index cards are recommended for user stories: they ensure the small size of the user stories and they are mobile / flexible to move around on a desk when they’re needed. Neither do you need a sophisticated drawing software to create a domain model. A pen on large paper will suffice.

What to do with the user stories and domain model?

First of all, the user stories have given you the details and the domain model explains how it all fits together. Now it’s the time to re-estimate the task. If a lot of details emerged that weren’t thought of before, the estimate might go through the roof. At that point it’s important to a) handle add-on requirements (get paid for the extra work) or b) ask the customer to get rid of some of the user stories so the estimate will meet the size of the contract. There’s a thin line between detailed stories and wanted features. The first describes the original task while the latter is a spinoff of the brainstorming session and thereby not included in the estimate.

When the stories are agreed upon the task is ready for implementation. But wait… this task is probably related to the bigger application in work, right? So it’s time to adress your peers and call for … the brainstorming session.