This is an egg.

This is an onion.

Now go make an onion omelette.

---

There is a flavour of documentation I call “All of the ingredients, none of the recipes”. I’m not sure I invented the phrase, but I’m sure I like it. It refers to the sort of documentation that tells you all the things the software can do but not how you can make the software do them.

---

Reference documentation for an onion will list many onions, and might even link to a video about the different ways you can chop an onion. But you’ll have to dig a bit to figure out which of those cuts of which of those onions you want for your omelette. And you haven’t even figure out how to handle eggs yet. In fact, you may not have picked the type of egg you’ll want. You can get quite a bit of omelette from an ostrich egg, after all, and I wouldn’t bet that the egg reference documentation highlighted chicken eggs as best practice.

Why would it? I didn’t specify how many people you’re cooking for.

---

The weird thing about the prevalence of the “ingredients, no recipes” type of documentation is that many companies ask you to write instructions for cooking an omelette/making a drink/getting cash out of an ATM as part of their hiring process. Documenting step-by-step instructions – task-based documentation – is not a new idea. Why is it struggling?

---

I’m not sure there’s a single answer to this question, other than “for one reason or other, a technical writer did not deploy their full skills”. What that reason is probably changes from company to company, and even from project to project within a single company. Are you not giving your writers enough time to understand workflows? Are you relying too much on engineering drafts that focus on each engineer’s work in isolation? Perhaps you don’t have clear content models to guide your writers towards task-based content?

---

“Recipe cover” might be the most important metric you could measure for your documentation team. Of all the content you produce, how much should be task-based, and how much really is? And have you figured out why?