Work flows vs specs

In the informatics world, we always talk about 'the requirements'. Agile handles these different from Waterfall, because we realize that all requirements seldom can be known up front. One of the things we do is collect 'Use cases'. For normal human beings like geoscientists (our users), this is still way too abstract. Use cases come with roles, actors and all that stuff. We have to realize that ordinary people think in 'Work flows'.

Work flows map very closely to use cases. Every deliverable we make enables one or more work flows. It's very important that we are aware of this - users need the tools to get their work done; that means getting their work flows supported.

Work flows are part of what we call the 'problem domain'. In the 'solution domain', these result in specs. Here's the thing. In large projects, you will probably need a repository for both work flows and specs. For smaller projects, almost always the specs are more important than the work flows. Huh? OK, in the grand scheme of things everything is important, but collecting unlimited amounts of work flows will not get you very far when building the tools. Not only because work flows are very often quite obvious. Even if they're not, they are often hopelessly numerous.

The specs on the other hand are much more orderly; they can more easily be listed. They are therefore essential for checking whether you have everything covered. So where there are many branches to work flows that would result in lengthy descriptions (often speaking for themselves), the specs on the other hand are always finite, allow ticking off, and you can much easier make sure you won't forget a thing.

Time for an example. Let's say we want to enable some kind of analysis on some kind of data. For this, user will have data from some source, get results, may want to plot it, etc. etc. The point is that if you just say 'this type of analysis must be supported', then very often there are many possible work flows, and they kind of speak for themselves. But the actual implementation has to enable all branches that can be gone into. User wants to see a diagram somewhere half way, save results, set input parameters, estimate coefficients, etc. etc. The specs list this; they show what is (going to be) supported and what not. Developers and users can check and say what they think is still missing (they generate work flows on-the-fly, in their minds, how cool is that?). Now imagine trying to capture all requirements/work flows. You sit there, sweating, trying to think of each and every use case that may appear. And sure as hell, you will miss a lot. When making the specs, things flow much more easily. Specify a 'store intermediate results'? Then sure as hell there must be some place that these will be read back. If you think about what places that could be, then you have enabled all the work flows that need the implementation of these specs.

Humans are bad with keeping accounts, but great with imagining work flows. Thus, we need some help with the specs, meaning we have much more need for using tools for uncovering them. Yes, for testing you will have to cover the most significant work flows. And the fun thing is, once you have the tools made, it's much easier to see what those 'significant' work flows are. But while making the tool, your back-bone helper is the repository of specs.

No specs?

"Agile developers just hop in before creating specs. This is because they know that the requirements will not be known up front, and have to be discovered during development." Is that true? Not entirely. What we do is refine the sketch that we make in the beginning of the project. Little by little, these specs become more and more complete, and we get more and more insight as to the true extent of the project.

At OpendTect, we keep the specs in wikis. These are nicely free-form, and it's easy to annotate with states 'done' or 'still need weeks to get this right'. Also time estimates go in there naturally. If something gives more trouble than expected, break it up in sub-bullets.

This particular example shows everything in green = done. My work. Hehe.

The nice thing is that there's always an overview on where we stand, and signs of problems can be seen rather easily. Also, it's very reviewable. Together with the executable system that should be updated as much as possible, you have a nice overview of the system: where are we now, what is still left. Prioritization is also easy to do. Just add a little tag to all items - the fun thing is you can do it on every level you want. You can tag a whole sub-tree as [Priority: High], or [Leave till the end].

Of course, in the end, the executable deliverable - that is the core of Agile work. Claiming something is one thing, the proof of the pudding is in the eating. But having a good backbone of the approach is a very important ingredient in getting there reliably.