Using Acceptance Criteria & Text based stories to build a common domain language between business and developer
Image via Wikipedia Besides precisely pinning functionality, writing text based stories has another – and some would argue more important – benefit, developing a shared domain language between the business & developers.
A large part of developing a new software application is defining and codifying a business solution. To do this, both sides of the equation must be molded to fit the constraints of the other – the business process needs to be expressed in a precise manner that can be automated in software, and software must be molded to fit the use cases of its users.
The mismatch between the way the business sees the solution, and the way the developers view the solution becomes painfully obvious about half way into the project, when you start to try to match what data fields are labeled on the UI, and what they are called in the database / object model.
I’ve worked on what should have been simple projects; where maintenance is a exercise in hair pulling as you try to figure out what data input results in the weird output in a report.
The root problem is a lack of a shared domain language. Projects naturally evolve domain languages; and unless guided, you can guarantee that the language in the customers requirements spec and that in the code base will diverge rapidly.
Sitting developers, testers and the customer together to produce written text user stories following Dan North’s classic BDD story structure goes a long way towards resolving this issue.
Talking through how functionality will work, and being forced to formalize it by writing things down helps the domain understanding and language to evolve naturally, influenced equally by the customers domain understanding, and the constraints the developer must work within.
Its vital that this is done before coding begins for the following reasons:
- All stakeholders have been indoctrinated in the same domain language
- Names for domain concepts are at hand when the developer needs them, resulting in better named domain objects.
- Both the developer and customer know exactly what functionality is expected; helping to keep both focused on solving the right problems.
- Facilitate ongoing conversations as the solution evolves. Evolving a shared language is difficult, and better done at the beginning of the project whilst everyone’s enthusiasm is high. With that hurdle out the way, ongoing conversations are easier, and the temptation just to guess, or devolve into an us vs them mentality is greatly reduced.
During release planning, the high level “As a [x] I want [Y] so that [Z]” is probably sufficient, with the “Given, When, Then” acceptance scenario’s being fleshed out at the beginning of each sprint.
Specifying your functional requirements as text stories leads to some exciting opportunities:
- Your “unit” of work is immediately available, and understood by all. This makes prioritizing which stories to include, work on next, or drop much easier
- Its possible to turn the stories into executable specifications.
The Ruby community has made the most progress in the latter opportunity, with their rSpec story runner.
Consider the possibilities of the following development practice:
- The team begin by specifying text stories & acceptance criteria.
- The testers turn this into an executable spec, with each step “pending”
- The developers then work from the executable spec, coding the functionality to make each step pass one by one
- When the customers receive a new version, the first thing they do is execute the stories, to see exactly which functionality has been implemented, and prove that all is still working as expected.
At any stage its possible to see how far the team is (how many steps pass?), speculative complexity is reduced because the developers are focused on developing only that which the test requires, and all the while a suite of regression tests are being build up!
![Reblog this post [with Zemanta]](http://img.zemanta.com/reblog_e.png?x-id=505a2f3c-65c4-460b-a75f-24129ace91c2)
Domain mapping with Wordpress MU, Plesk, Apache2 & Ubuntu
Given a Wordpress MU install on Plesk running on Ubuntu with Apache2, we want to configure domain mapping so that
user1 can have myblog1.com mapping to their wordpress blog (myblog1.masterwpmu.com) and
user2 can have myblog2.com mapping to their wordpress blog (myblog2.masterwpmu.com)
We need to configure quite a few moving parts:
- DNS for masterwpmu.com – this should be an A record, pointing to the IP of your server
- DNS for myblog1.com & myblog2.com – these should be CNAME records, pointing to the A record in (1) – eg. masterwpmu.com
- Apache2 – we need to alter the apache vhost conf created by Plesk to setup a wildcard alias
- WordpressMU – we need to configure it to serve the right content when receiving a request for myblog2.com or myblog2.com
When someone makes a browser request for myblog2.com, the following sequence happens:
- myblog2.com is resolved to masterwpmu.com, which is resolved to the IP of your server.
- the browser makes a request to the IP, port 80, passing the host header of myblog2.com
- Apache intercepts the request to point 80, checks through all its known vhost server aliases, and not finding a match redirects to the wildcard alias pointing to our WPMU install
- WPMU gets the request, matches the host header to the correct blog content, and returns the relevant page.
So, how do we configure this?
- Create a new Plesk site, with its own domain name (eg. masterwpmu.com) & install WPMU. Ensure this works.
- Create a new CNAME record myblog2.com which resolves to masterwpmu.com (Its also possible to setup an A record pointing to the same IP as masterwpmu.com; although this will break if the IP of masterwpmu.com ever changes). Google has a nice set of instructions for doing this on most major DNS providers (obviously you’ll want to point to masterwpmu.com rather than ghs.google.com
) - Edit the Apache2 vhost conf created by Plesk at: /var/www/vhosts/masterwpmu.com/conf/httpd.include, changing:
ServerAlias *
<Directory>
AllowOverride FileInfo Options - restart Apache2 ( /etc/init.d/apache2 restart)
- Log in to the WPMU install as admin, and create a new blog. Edit the new blog, and change the Domain & FileUpload Url to myblog2.com and http://myblog2.com/files (all the other Urls are automatically updated when you save)
- Browse to http://myblog2.com !
Gotchas:
- You can only have 1 wildcard Apache ServerAlias per IP
Hope that helps!
The Complexity Retrospective
Many projects go awry due to excessive complexity; and its always worth evaluating whether your team is approaching things in the simplest way that can work; especially when the deadlines begin to loom.
I recently lead a retrospective with my team focusing on complexity across all the areas of our project, using the a handful of techniques from “Agile Retrospectives – making good teams great” (a must have for every agile team).
As suggested, we structured the hour long retrospective into 5 parts:
- Setting the stage
- Gather data
- Generate Insights
- Decide what to do
- Close / Action plan
The purpose of “Setting the stage” is to get everyone engaged, and thinking about the same theme. To do this I reminded people of the actions we had set ourselves from the last retrospective, and then asked each person to complete the sentence “If we were a military commando, and our mission was last retrospective’s actions, we would be _______”
Awarded medals
Promoted
Ready for another mission
Court marshalled
Dead
I then told the team that in this retrospective we would be considering complexity, and whether we had too much, or just the right amount in each of the areas of our project.
To gather data, I drew a complexity radar, with each spoke a different area of complexity. I began by suggesting a couple of generic spoke names (Data model, Workflow), and then got the team to suggest the other areas. Using dot voting, everyone voted as to where they felt we ranked on each spoke, with closer to the centre being just right, and further away being overly complex. Joining the clustered dots produced the following radar map:
To generate insights we used the 5 whys excersize. I asked people to break into groups of 2, preferably cross discipline, and assigned each group 2 of the high ranking spokes. They were then tasked with asking each other “why is <spoke area> complex”, and “why is <answer>?” and so on, until 5 why’s had been asked. The answer to the 5th why was considered the root cause of the complexity, and recorded on a card. As the root causes cards came in, I grouped them, and when everyone was done, read the root cause groups out.
To decide what to do we constructed 2 more histograms, one considering the risk of the root cause, and the other difficulty to address the root cause. I then ask each person to vote which of the 2 root causes had had the highest impact & and which was the least difficult to address. This produced the following histograms.
In conclusion, we then combined the impact & difficulty histograms into the following map
My intention was that the final exercise would make it simple to choose the actions to take forward for the next sprint (basically chose the low hanging fruit – the easiest things to address which had the biggest risk reduction); but there wasn’t a clear winner shown on the graph. Generating actions took a bit more discussion.
We found that this format was a fun and effective way to address the complexity problem.
Hopefully you’ll find running something similar with your own team helpful!
100% code coverage is only part of the QA story
Luke Francl of Tumblon has a nice summary with backing research showing how unit testing is only part of the QA story.
Its important to realise that developers by nature will only test the happy path; hence its likely that those diabolical edge cases will remain untested by a developer.
Another important factor is that most bugs come from missing features or requirements; and its impossible to unit test what isn’t there.
See more at http://railspikes.com/2008/7/11/testing-is-overrated; specifically Luke’s create Venn diagram showing how different types of testing (unit, user, code review etc) uncover different types of defects.
This isn’t to say that unit testing isn’t worthwhile; it just frees your testers up to concentrate on the unexpected, non-logical things that users are sure to try use your software for 
Fixed price bidding vs the Cone of Uncertainty
Software estimation’s “Code of Uncertainty” suggests that before the requirements & user interface design is completed on a software project, time to complete the project can vary by up to 16x.
(Source: http://www.construx.com/Page.aspx?hid=1648)
So, before you have pinned down the exact requirements, the actual time to compete the project could take up to 16 times longer than your first estimate. Only after you have pinned down the user interface should you expect your estimates to be within 25% of the actual time to complete the project (an error % that can be managed). Note that this data assumes an experienced team, good estimators and NO additional requirements introduced late in the project (and good luck to you finding a project like that!)
Given this research what are the chances of a fixed price bid coming in on time or on budget? Virtually zero.
And what is the first thing to slip under schedule pressure – quality.
So, our theory implies – if you go with a fixed price bid for any significant piece of work, before the user interface has been designed, then:
- The work delivered will be late (somewhere between 4 & 16 times the original estimate)
- Work delivered closer to the delivery date will be of low quality.
Is this true?
What have your experiences been?
What is the definition of Done?
Scott Hanselman has a pretty interesting discussion with Scrum co-creator Ken Schwaber around the concept of when is a story Done.
http://www.hanselman.com/blog/HanselminutesPodcast119WhatIsDoneWithScrumCoCreatorKenSchwaber.aspx
Ken raising some interesting points, most notable that a well defined concept of Done, understood by all members of the project is a cornerstone of a good scrum process. Without it, you can guarentee that you are building up technical debt; and your software won’t be in a releasable state once you have “Done” all the features, which kind of defeats the point of release planning!
So, what is your definition of done?
- All acceptance cases / test scenarios pass?
- Unit tests pass?
- Performance tests pass?
- Customers have used and approved the feature?
