Posts Categorized: Agile Requirements

Last week’s Brown Bag: Project inception phase within agile software development

brown bag logo v1

  Last Friday, David offered us an overview of the project inception phase within agile software development. David began by establishing the context of business-owned incremental delivery: business-owned, because the value proposition is determined by stakeholders outside IT; incremental, because there are often commercial opportunities to exploit by delivering ‘smaller and sooner’. When dealing with… Read more »

MMFs – enabling incremental delivery

I just checked back to see how much I’d written about MMFs (minimum marketable features). This is a technique I use and talk about a lot so I thought I’d written more that I have. I’ll provide here a few of the ways I use MMFs and why I feel that they are so helpful [...]

User stories discussed

Last week I had the pleasure of running a user story workshop for a group of very experienced folk with a broad range of backgrounds and skill sets. We convened the workshop to discuss the challenges that present themselves when we apply user stories for the first time on a real project. The conversation was [...]

Agile Business Analysis at Agile2010

The slides for this session are now available for download   On Thursday Gary Jones will be talking about Agile Business Analysis techniques in E-3 at 13:30. This post brings together some of the resources he will be referring to and other related references. If you have a favourite resource for other BA techniques please… Read more »

Dangers of executable examples over dry documentation

My team is responsible for several web service APIs that are used by external parties. The standard pattern for educating users about these interfaces was to provide an API document which listed the calls possibly with the occasional example. I have always found this approach to be less than useful and not particularly accessible.

I prefer an approach where the API specification is very much example based. This is makes more sense for RESTful web services than a programmatic API as there is no accepted mechanism for declaring such an interface. The same is not true if you are declaring, for example, a Java interface.

We supplement the document with JMeter projects pointed at a reference system which allow these interfaces to be exercised by the consumer and provides a step by step demonstration.

This has been an excellent mechanism which has resulted in very quick uptake of our interfaces but yesterday I was provided with an example of a potential pitfall:

We provided an API which upgraded widgets. Version was supplied with the manifest of the software package being supplied and was used again in the query string to the upgrade service. The reference data supplied by the system put the current version into a title metadata field so that testers could easily see that the upgrade had been formed. The version in the title matched exactly the title in the manifest.

Weeks after delivery and demonstration it stopped working. Why? The client was using the title rather than the metadata it was supposed to. Since we had used the same value for both the end to end use case appeared to work. As soon as they started using real data where the title was no longer equal to the version everything broke.

A valuable lesson here for me to relearn (I have hit it before in similar contexts). Always make sure reference and test data attributes are not interchangable with each other without an error occurring (and being detected). I should have made the title attribute ‘The version of this widget is <x>’. That would have steered the client developer away from error and would have caused a validation error then first time he tried to submit it to our application.