Documenting Documentation

Creating software that works is hard work, it takes time, expertise, and experience. After all that hard work the last thing a developer wants to do is spend time answering “silly” questions asked by the users using that software. The best way to fend off most basic questions is to tell users how to use the software – to provide documentation!

All of us have seen the “readme.txt” file that comes with a program we’ve downloaded. Most users ignore it and decide to open it only when they can’t figure out what they are supposed to be doing. It’s at this point the documentation becomes most important – the user is actually looking for it!

What makes documentation so important is that it’s the only resource your potential users will have to turn to when they’re trying to figure out how your creation works – and if you want to avoid asking “did you turn it on?”, the best thing you can do as a developer is provide some detailed content on what to do, and how to do it.

Quick Start

If your application is as easy to use as turning it on and watching the sparks fly, say so! If there’s more advanced features and functionality available, describe that later on. Most people don’t want to spend time flipping through pages of “installation”, “configuration” and “usage”. Tell users right away that after installation they need to enable this and disable that. Once you have that out of the way you can talk about more specific details.

Installation 101

Don’t assume that everyone has installed Joomla!, installed extensions into Joomla!, or that out of the hundreds of other places to turn for tips on installing extensions your users will know how to do it. Describe the installation procedure, or provide a quality resource on it.

Document the Interface’s Functionality

Remember that assuming that users know something they don’t is when most developers get into trouble with support. Tell people what all the buttons, switches, drop downs, and toggles do. A great interface design will also go a long way and make this process easier. Brian Teeman, an experienced Joomla! implementer and project co-founder writes on the topic of usability. A pro-interface with documented functionality will give you more time to develop and less time answering simple support tickets.

Go Outside Your Peer Group

Getting another techy, geeky friend to review your documentation is not going to help you write good documentation. Most likely they know what you’re thinking and they’ll be able to guess their way through your application. When I wrote for the Joomla Documentation Team I had my brother, a guy who had trouble checking his email, go through the steps I had written to check and see if they made sense. I received many compliments on the detail of my documentation, and I attribute that success to having him regularly say while following steps “what does that mean?”.

Keep in mind that ‘wordy’ is not detailed - detail is precise and direct. Order people around and give real direction.

“A picture is worth a thousand words”

Include screenshots that mean something. A shot of an administrator area is not helpful – a shot of a few specific control panel buttons with one of them circled and labeled is. Video is great, but it’s a bit more difficult for people who want to scan through and find exactly what they’re looking for, so watch out for that.

Document The Demo

Most people choose a particular extension because they saw what it does. And they want *that*, not anything else. Tell people what settings you used to get your demo (or include those settings as demo-data, even better!) to do what it does. Since you’ve documented each of the settings, custom settings will be easier for them to make without forcing them to figure out what you did.

Troubleshooting Tips

If you find that you’re getting a lot of support requests on one particular thing, read your own documentation. Did you identify the specific instance people are dealing with? Add a troubleshooting tips section and add to it as needed. Remember this is to help you, just as much as it is to help your users. Less time supporting means more time developing, and a few less gray hairs.

Be Multilingual

If you have the ability to offer your documentation in multiple languages, do it! The Joomla!-sphere is worldwide, and offering your documentation in another language will further encourage that eco system.

I thought it would be an important contribution to hear from a developer who supports documentation for some very complex Joomla! components. So I spoke to my colleague Nicholas Dionysopoulos, who offered these suggestions:

People hate reading

Just because you've written documentation, it doesn't mean that everyone will read it. Be prepared to be asked questions that have already been answered to the documentation. If you have a support ticket system or a forum, you'll witness a pattern evolving. The same 10-15 questions pop up on a daily basis. Use that knowledge to produce a knowledge base / troubleshooting guide. You get bonus points by actually redirecting people to select pages of your documentation based on the problem they're trying to solve, instead of paraphrasing your documentation in yet another document.

People love watching

Nobody will read a two page "Getting Started" guide even if you pay them. However, virtually everyone will gladly watch a 5 minute video tutorial with the same content. Producing a screencast is fairly easy. If you don't feel comfortable speaking while working on the computer, write a script (like a movie script!), rehearse it and record it. Or, record the screencast and have someone more confident in English do the voice over. You get extra points if you manage to convince a female friend with a friendly voice to do the voice overs for you.

“Patients lie” –Dr. Gregory House

People will often tell you that they have read the documentation, but they have this and that problem. Don't assume that because they said so, it is so. Most likely they browsed through the documentation and they missed the paragraph which describes the solution to their exact problem. Don't be afraid to link them to your documentation or paraphrase a small passage if you suspect this is the case. This is what separates excellent support from the rest: being able to point users to the correct paragraph of the documentation.

Single source, multi format

On-line documentation is useful only if you are on-line all the time. Don't assume that because most westerners are connected to the Internet 24/7 this is the case in all places of the world or possible for all users. Some countries don't have broadband service and connections are slow and expensive. In other cases, it's impossible for the user to be on-line all the time. These people won't use the documentation unless you provide it in an off-line friendly format, e.g. PDF. The best way to ensure that is to write your documentation in a suitable format, e.g. in DocBook XML format, then produce the on-line and off-line versions of it from that single source.