It came in conversation to the topic of chickens, since we were sitting in a yard that had a few running around, and others in the group also had chickens in their yards. The “beer can chicken” cooking method was discussed. The instructions were given as follows: open beer can, insert can into chicken cavity, cook the chicken (upright rather than on its back was later clarified. That way the beer evaporates into the chicken instead of spilling all over it). But then they also mentioned that first you should have a dead chicken; stuffing a live chicken’s cavity with a beer can might prove difficult.
And then it occurred to me: How many times do I search for help, whether it be on customizing some feature in WordPress, simply making something work that should work but doesn’t, or hooking up some other kind of code – my days of modifying actionscript in Flash come to mind – that comes with instructions that do not include making sure you have a dead chicken first?
Of course, it is assumed that the chicken is not only dead but plucked of its feathers and cleaned, with the head and feet removed. How many developers assume that their plug-ins and code examples are falling into the hands of those with enough experience to have everything that is “assumed” by them? As a designer, I can look at a page of code and most of the time tell what is going on, but I don’t always know how to insert a modification or customization into an existing coded page or application.
One solution would be for the developers writing instructions to add examples that are complete, instead of snippets that need surrounding code to work. Another is to perhaps let the user know what needs to be in place before it will work. I think that the more experienced users will simply skip over the introductory “first, start with a dead, cleaned chicken” part of the instructions.
I’m not really talking about “replace this chunk of code with this other chunk of code” type instructions, but ones that are a bit more complex, such as adding a new advanced custom field. There’s a bit of work to register those things so they show up, and a lot of options in their samples, especially when images are involved, but the samples are a little on the sparse side in my opinion. I’m not always sure what to replace with my own text, for instance.
If I were a programming expert it wouldn’t be a big deal, but unfortunately I am not. So often am I left wondering why the chicken is being so uncooperative.