Rob Redpath is the product manager for most of the co-op’s software products, and works with clients, analysts and developers to ensure that the software that’s developed is the right solution to users’ needs.

When you’re writing documentation it’s really easy to gloss over important details, or not really think about what it would be like for someone else to follow the instructions.

At Open Data Services, we use the First, Then, Finally method to think through the process, stay focussed and write useful docs. It helps us to be a bit more consistent without being overly prescriptive.

First, Then, Finally can be used either explicitly, or to provide the underlying structure for the documentation. It even works when the process has lots of steps, is fuzzy, or has lots of decisions for someone to make.

The format’s pretty straightforward: say what someone needs to do first, then what they need to do next, and then what the last thing they need to do is.

At each step, also ask what assumptions are we making about the person, and record if there is detail that you’re glossing over, but that is well-recorded elsewhere.

First

Define a clear entry point for the procedure. Here, you can set out what you expect the reader to have done, what they need to have ready, and where to start.

Then

Define each step, at whatever level of granularity you’re aiming for. Making each step explicit makes changes in granularity really obvious, so helps you stay consistent. Decisions can be a “then” as well — although if the paths as a result of the decision are quite different, then this might be the time to split up the document.

Finally

Give the reader a final step as a clear exit point, to know that they’re done, and to signal that they achieved what they set out to do, and can get on with whatever’s next!

For larger articles, we use Miro to map out the process and then go back to write up. In the example below from Open Contracting’s Kingfisher tool we built up the docs together with a facilitator, someone doing the task for the first time, someone instructing them on how to do the task, and someone taking notes.