Boilerplate Instructions, Bane of Modern Software


I bought a new theme to install for a client this week.

Normally, installing a theme is simple. Select theme, upload, install, done.

Unless the theme maker has decided to deviate from the standard protocols that we all know and love and which we have been happily following for years.

At that point all bets are off. Basically, the only choice now is to open their documentation and start reading their instructions line by line and following every micro-directive verbatim.

That is, assuming they have actually bothered to tell you what each little step is.

But no, in this case they just told me in generic terms to do what I had already done; the same thing that had already failed miserably.

“Go to the Appearances menu and upload your new theme.” they say.

Boilerplate instructions.


Now what?

Oh, yeah, figure it out for myself!

Talk about lazy and thoughtless. Not a great combo!

They didn't even bother to test their own theme and discover that,

…Oh wait, we packaged it in such a way that the theme is named something completely different from what most people will expect and it's also buried in a series of subfolders along with another thing that's called a child theme and you're just supposed to know that you don't actually have to use the child theme, but if you do, you'll need to install that first and then…


Here's the opportunity…

Test your instructions exhaustively and triple-check your documentation!

Having clear, excellent instructions that actually work is just as important as having a great product.

Junk instructions could cause someone to mistake your product for junk since it's likely they'll fail to get it to work as intended.

And then they might just ask for a refund.

Aha, instructions just became as valuable as the product itself!

Funny how that works.


Photo by Seth Anderson – CC Attribution-ShareAlike 2.0