As I’ve just set up WordPress for this blog, the first I’ve messed with WP in a long time, I got to pick a theme. The themes are all configurable. Some of them even have docs!!
Well, they sort of do. But mostly they’re push-button docs. A feature appears in the Customize controls called something like “Hero Upper Standard Widget”. It has some options. One of those might be called “Enable widget”. If you go to the docs for the theme, inevitably, they say something like “To enable the Hero Upper Standard Widget, choose the Enable widget option from the options menu.”
No explanation of what the hell a Hero Upper Standard Widget is, let alone what might be a good use for one.
So many docs across software in general fail to provide context. They fail to provide a pathway for learning to think. They assume too much, then only give you rote directions for accomplishing the one shining path the author envisioned.
Instead, try providing context first (What’s a Hero Upper Standard Widget), teach a little about it, and then you can give your step-by-step instructions with commentary that reinforces the context and knowledge. Provide positive and negative use cases (eg. “You can use a HUSW to display content that should always remain at the top of your page, even when the user clicks a sidebar item.” and “Don’t use one if you just want a header image. See the Header Image section instead.”)
Your users will be a lot happier.Buy Lincoln, Fox and the Bad Dog on Amazon.com right now, or get the first half for free right here if you're still on the fence (.epub download to read in iBooks, Google Play Books, etc.)