Recently, I’ve been thinking about food recipes, and how they help us with documentation. The observation that recipes are another sort of technical writing isn’t new – it’s expressed in one of Tom Johnson’s blog posts and a recent TECHWR-L thread, for example. But what I don’t often see are many thoughts on how knowing this helps (Tom’s interesting analysis notwithstanding). That’s why I decided to compile a list of things I’ve noticed when reading food recipes on the web, and how we might want to emulate these in our own material:
Observation One: Recipes emphasise pre-requisites
By ‘pre-requisites’, I mean the ingredients, tools and time needed for a recipe. Look at this cake recipe on the BBC Food website – ingredients and equipment come right at the top, and time taken is prominent in the recipe’s sidebar. Now, it’s true that most people using our manuals don’t need any extra equipment besides their computer and the app they’re already using. But they might need time, privacy, information to fill in, or have other ‘soft’ requirements. Time might need to be uninterrupted, information might need to be pre-compiled… recipes show us how to effectively communicate pre-requisites, explain alternatives (like substitute ingredients) and how to match them.
Observation Two: Recipes use formatting for semantic value
In most cookbooks, page structure visually distinguishes certain classes of information. A recipe’s ‘ease’ rating might always come after its title, for instance. Similarly, we should try to give formatting semantic value – for instance, placing similar tasks in a distinctly formatted sidebar, or only bolding UI elements.
Observation Three: Recipes show us different ways of organizing content.
How might a cookbook arrange recipes? It could do so by
- Ingredients – dishes that can be made with certain pre-requisites
- Ease – dishes to be performed as the cook learns more
- Diet – dishes that don’t break dietary laws (whether religious or personal)
- National origin – dishes that fulfil a certain kind of theme
We could arrange help topics in similar ways, by
- Fulfilled pre-requisites: what to do in certain circumstances
- Simplicity: deferring some knowledge for advanced users
- Conditions: separate out tasks that could be hazardous for certain situations
- Themes: tasks which pertain to quite disparate uses of the application
- Print paper forms for collecting information to be input
- Prepare notifications for a customer they’re serving (for instance, a password-changing procedure could help me tell my users about their new details)
- Prepare a record of the action for a timekeeping / HR system
- Comments fields. These comments assess how well the recipe worked, and maybe augment it by detailing a few substitutions for particular ingredients.
- Recommendations / rating systems.
- Social media reposting tools. This includes Facebook ‘Like’ buttons, re-tweet links and the like.
- The ability to create personal folders / scrapbooks of favourite content, distributed (at most) to family and friends