Slow-roast documentation

Yesterday was my wife’s birthday. As a result I spent 3 hours in the kitchen, accompanied by “technical documentation”. I cooked a “special meal” and that meant resorting to the most ubiquitous of tech-doc... the recipe. I don’t often use recipes, most of the time I prefer to either make it up as I go along or, better yet, let someone else do the cooking! However, when it’s an important meal, I write lists and use a recipe for everything that goes on the plate just to give me peace of mind.

I could tell you what I cooked, but I feel that if I dwell too long on the succulent stuffed leg of lamb and its various accompaniments the generated drool would swamp your keyboards. Instead we’re going to explore where the recipe came from, and how it impacted my view of “documentation on the web”.

I got the recipe from TESCO (for foreign readers, TESCO is a large supermarket chain; don’t worry, they may be extending a corporate tendril opening a store in your country soon). I didn’t buy the recipe, I obtained it from the Real Food website they manage. The website is essentially a massive cookbook with multiple search options. The website has become a favourite of mine because I can search for recipes based on what I’ve got in the fridge, the time I have to cook and how many people I’m looking to feed – apparently it’s also possible to search by calorific content, but that would just take the fun out of things. The first observation about the production of documentation is that people are more likely to use it if they can find what they’re looking for. This may mean that we want to reconsider packaging documents into .pdf format quite so often, especially when we’re dealing with end users who aren’t so comfortable with pressing CTRL+F. On-line shopping portals offer some excellent guidance as to how information can be sorted and filtered by the end user and it would be nice to see such an approach used more widely in technical documentation.

It didn’t all go smoothly with the meal. The juicy agneau rôti was on the big side, and as a result the timings in the initial recipe didn’t really work. This meant that the family got to wait an extra 45 minutes for their dinner. I posted a comment on the recipe page, and was pleasantly surprised when the team responded by updating their recipe as a result of my comments. I feel that this shortening of the loop between the author and the end user is a good thing, especially when it results in tangible benefits and essentially “free” usability testing... now all I’ve got to do is convince them to send me free food and all will be well!

Andrew