How to implement a spec

A dev plan is not a spec. Most proposals and quotes that clients sign-off on are specs, but they should be signing off on dev plans.

The difference is small but crucial: a spec is a list of features or things that will be done; a dev plan is the means by which those features will be created.

The reason this matters is subtle. It’s relatively easy to enumerate all the features of a system. For example there might be a login page, and a dashboard page, and a report page. So three things, simple right? But imagine those features take a 1 week each, what does the client see after week one? i.e. after logging in, what does the client see?

The spec doesn’t tell you the answer and so usually the developer will make their own mind up. This typically means the system will be unstable until all three features are implemented, which isn’t desirable. It means you can’t use the system because you don’t know what will work, and so you can’t give your feedback.

But a dev plan describes the process to achieve the result, at every step of the way. So the last issue in sprint1 might say “you see a blank page after logging in”.

This might sound like a trivial distinction, and this example is intentionally simple, but having a sequence of clear steps with definable starts and ends means issues can be made clearly distinct and easily signed off. And it prevents developers rambling on through a heap of features without ever getting to the end.

At a practical level, the way we ensure that the issues we create are a dev plan and not a spec is for every issue to have one or more testables. A testable is just a list of steps that are part of the issue that describe the output, so an example might be:

login as admin
select reports from the main menu
confirm you see a pie chart with 4 slices
the rest of the screen is blank for this issue

There are a few things to note about this example:

Each line is human-readable, so a non-technical user can follow it.
Each line is simple and to the point (we have a rule that no more than 7 long words are allowed per line).
And each line assumes the reader (either the developer, the tester or the client) is familiar with the system.

That last assumption is important. We don’t describe the full steps to login, including entering a valid password etc etc. Those steps would have been implemented and tested in an earlier issue and the team is familiar with them, so we can simply say ‘login as admin’.

Properly done, testables can be shorter than a description and more helpful. In fact, since we’re trying to avoid adding admin and not add a new headache to the spec process, we frequently skip the description altogether and just write the testables. In our experience this has never harmed the intelligibility of the issue.

We do find developers new to our process struggle with what seems to them like a pedantic approach to issue definitions. Frequently for those developers we see them creating issues with a paragraph of description and a testable like “1. confirm it worked”. This is not helpful. And it really can be hard to switch the mind towards thinking of the practical definitive solution to the problem rather than a broad ‘I kinda know what to do here’. But with a bit of practice at getting the level of simple yet precise wording right, the effort is equivalent to writing a description and the gains are worth it.

And needless to say estimating such an issue is significantly easier. For example the developer doesn’t have to imagine how much error checking is applicable to the issue, it’s either in the testable or it’s not.

The result of a dev plan with a testable like this on every issue is that the dev plan looks and feels more solid, the costing is more reliable, and it’s easier to say if any given aspect of the original requirements is accounted for.

No more wondering if the developer knew that the forgot password link had to send an email or not.