Annoying. Tedious. Time-consuming. Frustrating. Pointless. These are some of the terms you’ll hear from anybody that has to write documentation, whether it’s for their apps, themes, plugins or extensions. It’s the classic development cycle; all the fun comes with the designing and implementation of features, then the frustration sets in once most of the work is finished and you have to worry about fixing bugs and trying to explain to people how this thing you’ve poured so much time into actually works; it’s like running a marathon only to hit a muddy bog in the last mile! But if it’s so irritating, why do we still do it?
There’s a multitude of reasons, but we can probably define a few basic ones that will apply to the majority of cases. First, documentation is like a chronicle of the development process, noting all the features that have been implemented and how they work. In this case it’s not so much about providing a troubleshooting or user guide for customers, and more about getting eyes on the feature set you’ve built into your software so users know what makes yours a better choice than others, or just so that people have a way to learn about more obscure features; it’s not much fun to spend a ton of time on implementing a feature only for it to be ignored because people don’t know it exists!
Secondly and the area we want to discuss in this article, is to save money by providing the equivalent of first-level support for your product.
Save $$$s with this one easy trick
Alright, so I skipped ahead a little bit there. The purpose of creating documentation isn’t to save money, but it is often a natural consequence of doing so. What it is meant to do is save time, which for developers is a much more valuable resource. Let’s break it down; if software products, rather than services, are the main purpose of your business, then to maintain profitability you either need to be regularly releasing new products, or sustaining your existing portfolio with compatibility updates, feature additions and bugfixes. There are peripheral elements that come into play here, such as marketing and customer service, but even if those elements are perfect, if you’re not developing or maintaining at a constant pace then you simply won’t have the product to sell (no-one’s going to buy an unsupported, outdated product after all!).
With this in mind, anything that you can do that frees you up from more mundane tasks (that is, saving time), will as a consequence provide you with more time to work on development and maintenance, which will in turn save or generate money.
When it comes to after-sales support, there are often two ways the situation is approached; either a team is specifically hired to provide the support, costing money, or in a smaller company the developers will often join in the fun, costing development and maintenance time. In a perfect world you’d have the time and money to deal with each individual customer personally, providing bespoke solutions to their issues as they arise. In reality though, it’s rarely possible to maintain this level of support, so alternatives that take the pressure off your support/development team are needed. If your documentation is extensive enough, then you can significantly reduce the number of support requests that you receive since users will be able to find solutions on their own, or can be redirected to the resource if the request is submitted via your help channels.
Time Spent vs. Time Gained
If it’s your job to eat a frog, it’s best to do it first thing in the morning. And If it’s your job to eat two frogs, it’s best to eat the biggest one first.
So there’s certainly a case for the benefits of providing good documentation to your customers. But there’s a problem; writing documentation is still darned tedious. Unfortunately, there’s little we can do to make writing guides interesting, but we can bring some comfort by invoking the importance of time spent vs. time gained, or investment vs. return. Writing an extensive piece of documentation might well be the literary equivalent of eating a frog, but when measured against the consequence of not writing documentation, or (/gasp/) writing bad documentation, it makes far more sense to spend some time early after or just before the release of your product to write something that will guide your users through some common issues/implementations, rather than saving time by not writing the documentation and then suffering death by a thousand minor support messages over the lifetime of the product.
Make your documentation effective
Writing good documentation isn’t the easiest of things to do, often requiring plenty of testing and guesswork to find the layout, style and complexity that fits for you and your audience. However, it’s worth taking the time to do so as it will give you a ready-made resource to redirect users to when they have general questions or want to expand their knowledge. With that said, here are a few tips to help you along the way:
Write for your lowest common experience level
The point of making good documentation is to lower the number of minor support requests you receive; that means you should wherever possible avoid writing at a level of jargon that only the experienced will understand. Consider the average customers that buy your product, and tailor your language and explanations to fit lowest common experience level. The keyword here is common; no matter what kind of software you create there’s guaranteed to be at least one customer who has zero experience, no desire to learn, and a complete inability to follow simple instructions, but they’re (thankfully) extremely rare. Instead, think about the demographic you’re targeting; if you’re building something that beginner users will want to use, such as a WordPress gallery plugin, then your documentation should work from the assumption that the user might not be aware of common terms such as widget, dashboard et al, and will be far more comfortable with step-by-step instructions that guide them through the process. On the other hand, if your plugin is only of niche interest to experienced developers then using jargon and avoiding explaining simple WordPress concepts that every developer will already know is preferable. Know your audience, and build accordingly.
Layout your sections logically…
…But clearly separate them. If that user who fits the lowest-common-experience-level description decides to jump in to your documentation, then they’ll need a clear, logical progression through the topics so they can work through each section step-by-step, from installing, to troubleshooting and customization. However, while an inexperienced user will benefit from a logical progression, more experienced users are far more likely to jump through topics or search the document to find the exact bit of information they’re looking for. Pay careful attention to your headings and make sure each new section is labelled correctly; if someone who knows what they’re doing struggles to find something on their issue in just a few seconds then they’re far more likely to contact you directly for support. Separate it up, label it, and you’ll be safe!
Get into the mindset of your customers…
And get one-step ahead of them. Documentation is meant to help you lower the number of support requests or increase the speed that you can deal with them, right? So the more you can do to eliminate an entire chain of support queries, the better. Picture a scene; you’re a newbie with WordPress, and you download a plugin that adds a visual element (we’ll use the gallery plugin example from earlier) to your content. But there’s a problem; when the gallery’s inserted into a page it has a color border that clashes with your site aesthetic. Not sure how to change it, you open up the documentation and find the section on customizing the border, and it says: "Border color can be customized in CSS". What’s the next thing you’re going to do? There’s a good chance that you’ll contact support asking the next question in the chain; "What part of the CSS needs to be changed, and how do I do it?", which means the developers are getting one more support query they didn’t necessarily need to receive. On the other hand, some users won’t even bother to ask; if they don’t find the answer they’re looking for in your documentation then they’ll just bugger off and try out a competing product.
This is a fairly silly and basic example, but the purpose was to demonstrate the principle; if your lowest-common-experience-level user is going to be quite inexperienced, then your documentation should, where possible, attempt to predict the kind of follow-on questions your users will ask and pre-empt them accordingly.
Don’t be afraid of redundancy or updates
It would be nice if we could be certain that everybody who uses a product will also thoroughly read the documentation from start to finish, equipping themselves with complete knowledge of the available features and how to implement them, but the truth is that often users will be just as pressed for time as you are and may just rush to find their answer as quickly as possible. So what can you do to help them on their way? Laying out sections logically has a big impact, but also consider (especially in large projects) that different users may have different ideas of where to find particular information. I’ve actually seen this applied in Gavick’s documentation for the TechNews Magazine theme; the theme relies heavily on the News Show Pro plugin to create its layout, both in widget and shortcode form. The documentation offers details of News Show Pro in two separate sections; a frontpage section that’s specifically addresses how to customize the widget on the frontpage, and another section in the Theme Features area that explains the functionality of the plugin in general terms, and both sections note the additional information that can be found in their counterpart. It may seem redundant to have similar information added twice to a guide, but the point is to make the documentation more intuitive for as many kinds of users as possible.
In the same way that it’s good to try to predict how customers will act, it’s also important to learn from what they do. Did your last release’s documentation miss an important area that lead to a large amount of support requests? Then consider updating the existing documentation to cover this new area. If you’re often releasing new products on a regular basis then going back to update documentation for a product that will soon be obsolete might not be the best course of action, but you can learn from the experience and take those lessons on to your next documentation project.
Summing Up
We apologize profusely, but we’re afraid that creating documentation is still tedious and often boring. However, bearing in mind the suggestions above can help you get some value out of the process in terms of time saved while also providing a clear benefit to customer satisfaction; anything that will allow your users more freedom to discover solutions and learn for themselves is worth the time-investment, even if getting the documentation right will take some extra effort.