Tips to create a useful user-manual.

Question

If I start writing a user-manual for applications I have written, I have a hard time to look at the application from a users standpoint.

I know it's not very useful to write something like: To use the foo-function click on the foo-button, choose the foo-type from the list and type a foo-name. After that you can click on submit and your foo will be created.

But often it's the only thing that comes to my mind, if I write the documentation.

Do you have any suggestions, what for useful things can be written in the manual?

Edit: As the nature of my question makes it impossible to have one 'correct' answer, I list here the main points, that are useful from my perspective. Thanks to RoBorg, Andy Brice, Martin Kool, HLGEM, rmeador, geometrikal.myopenid.com, dan gibson, Mitchel Sellers, Kevin Lamb, chakrit and VirtuosiMedia for these suggestions:

• Examine, how someone else is using the application. Especially someone, who doesn't know it yet.
• Include a 'quick start' guide and a more in-depth step-by-step tutorial.
• Don't use the terms you use as a developer, try to find the terminology of the user.
• Include screenshots. Put arrows and circles in the screenshot, to highlight the function you want to explain.
• Explain simple features in a matrix.
• Explain step-by-step scenarios for what the user may do. Provide screencasts for explaining processes.
• Use a wiki.
• Include documentation for processes that happen not very often. This are processes, the user may have difficulties.
• Include a trouble-shooting-guide.
• Test your quick-start-guide on a clean box with a fresh install. Nothing is more annoying, as the simple example isn't working.
• Include all necessary information in the section there it is needed. Repeat the information if needed.
• Explain why this function exists and not only what it does.
• Focus on problems and how they can solved, not on functions.
• Show examples of cool stuff that can be done with your software and explain the way how to do it.

Answer 1

Watch someone else use it (preferably someone who has never seen it before) - that's always an eye-opener!

Answer 2

I have found that writing manuals in an order where they walk the user through the processes/functionality are the best. SO you are walking them through, do A, click X, etc, but the key is that along the way you explain the what, why, how, and when behind their actions.

Doing this will give them the insight on how to properly use the system.

Answer 3

Did you have testers? Get them to help you write the manual, or at least get their feedback on what works, what was hard (needs better documentation), etc.

Try walking the user through a process:

Your goal: Make the text bold. First select the text you want to embolden. Then click the edit menu. Click Bold.

Include lots of screenshots too, those are much easier to "read."

Answer 4

You should not be asked to write the manual, one of the superusers should write it, but you should be available for questions and comments. In most cases that is unfortunately not how it works, but I once wrote the manual together with a superuser and the result was great, as it showed the system from a users perspective, not mine.

Answer 5

I suggest reading the book "Don't Make Me Think" by Steve Krug. While it is superficially about web design (though it mercifully doesn't contain any code) it is really about writing interfaces which need no instruction. It's a short read. At the end there are a few chapters on doing cheap, fast, effective usability tests and user trials.

Answer 6

I am going to agree with Mitchell. Provide users various scenarios that make sense to them. You could then show each step with a description, and a picture showing them where they are in the process.

One great way to go about this is to provide an online screencast or companion cd that has the screencasts included.

Answer 7

I would create the documentation on a wiki. Ideally, this wiki would be exposed to your users and they could modify it to suit them, but even if you're only using it for internal developers to keep the documentation up to date and in one place, it's a good start. You can always export to some format like PDF from the wiki. If you're going to have a customer-facing wiki, you can seed it with info like the example you describe and flesh it out as needed (and so can the users).

Answer 8

pretend you are explaining the software to a slow 5-year-old, then simplify it ;-)

Answer 9

• Include contents and an index.

• Use images where appropriate.

• Break up large chunks of text.

• Use hyperlinks.

• Include a 'quick start' guide and a more in-depth step-by-step tutorial.

• Only use terminology user will understand. For example, most users have no idea what you mean by "Dialog", use "Window" instead. Include a glossary, if necessary.

Answer 10

See also this question about a Support Documentation Handover: http://stackoverflow.com/questions/205374/what-are-the-core-elements-to-include-in-support-documentation

Answer 11

I don't know of any documentation patterns, just some practical experience I can share.

Functionality such as what buttons are best to be written out in a matrix view, without spending too much proza on it. In our experience, people will usually understand that a bold button makes text bold.

For your application, you usually have a set of domain objects in code. Those objects are the customer's domain, it's what the customer relates to and understands. The most common tasks for your customer will be manipulations on those domain objects, so we'd usually describe such manipulations in simple user scenario's with short lines of text and clear images.

The less text and the more images, the happier the customer. That was our motto and so far everyone is happy.

And if I may give you a tip: try use a wiki. Wiki's are excellent for quickly writing out certain aspects of you application, without you having to pre-think all that you're about to write. You can simply type a few pages in a form that you like, and regroup them later on. For the past two years we have used Trac as our form of documentation, but of course it also depends on your customer's needs and know-how too.

Answer 12

Get a lot of eyes on it.

Your mom, your dad, your sister, your friends.

Or that sales person in the next cubicle.

Or speaking generally, get a fresh perspective from someone else.

They can often show you what the gotchas for the users of your software will stumble upon. Those are manual-worthy materials.

Answer 13

Your perspective is often this the what each page does - here's what you can do on each page. The user though thinks in terms of the processes he or she has to handle. Write the documentation that way. Here are the steps to add a new customer, here are the steps to create an order, here is how to cancel an order, etc. Especially be sure to document processes they don't have to do very often, these are the ones they will most likely be turning to the manual to find out how to do. For instance what steps have to be taken when a task needs an approval to get completed and it is turned down (most people only document the main path on the flow chart not the paths that only happen occasionally.)

I find it particularly useful to include some trouble shooting steps - here's what to do if you get this particular error, here's how to report an error so that the programmer can reproduce and fix it, etc.

Nothing can substitute for time spent actually observing real users using your software when writing documentation. Chances are you will also find some places where the software isn't effective for how the users work. This would be things like forms that have the columns in a different order from the paperwork the user will enter it from for instance. This is causes data entry error problems (and lots of wasted time) if people have to skip around.

A picture is worth a thousand words, you can't possibly put in too many screen shots. Use arrows and other graphics to point out what you are talking about.

Answer 14

Find a very well written manual and use that as a model.

Answer 15

I agree with Andy Brice with a couple of more points:

• Don't be afraid to repeat yourself whenever necessary, as its easier for the user if all relevant material is contained in the section they are reading.
• Keep sentences concise. Put wordy explanations after procedures, not together.
• Put troubleshooting comments with the section they are relevant to as well as at the end.
• Physically go through your quick start guide or tutorial on a clean machine to make sure it actually works.
• Most times I like to write sections of the manual so that if the user wanted to, they could print out only that section because it contained all the relevant information.

My real life example of a well written flawed manual:

I bought a GigE Vision compatible video camera for an engineering project. I opened to the getting started section, and followed all the instructions to the letter. The guide was well written with images and explainations, however I could not connect to the camera. After hours of racking my brains I finally find in an obscure section of the manual that the camera doesn't use DHCP. Unlike the standard, it has a fixed IP address and I have to change my network settings. This information should have been in the section where the user (me) first connects with the camera. It's not good having to make the user search for this information.

Answer 16

Here's a link you might find helpful: The best user manuals EVER.

Answer 17

1. Explain why I would want to click the foo button. I was looking at an option on my router yesterday and I didn't know what it meant. I looked at the help but it basically said "click this button to enable foo", without telling me what foo was.

2. Have a look at the dummies/idiots/head first books.

3. Read Kathy Sierra's website. She worked on the head first books and although the site is inactive still contains lots of good stuff about writing manuals. http://headrush.typepad.com/

Answer 18

Users want to feel empowered by your application. They don't care if your application is cool, that will wear off (even if it is cool), what they want is to do cool things themselves. Kathy Sierra recently spoke at a conference (video, which is definitely worth watching) and something she said really stood out to me. She used the way cameras are marketed to illustrate her point.

The way most cameras are marketed is by showing all the incredible and beautiful photography that you can take with the camera. People want to be able to do that, so boom! they buy it. Then they get the manual. The manual is all about how to use the camera, but there isn't a thing in it about how to take fantastic and amazing pictures. People get bored with the minute details and so they learn a few of the options and then settle for that. They end up taking pictures with heads cut off, poor lighting, etc. and soon the camera only comes out for birthday parties and special occasions, which is definitely not how the camera makers intended it to be used.

The point of all that is, make your manual all about the user, not the tool. Yes, you need to have instructions on how to use it, but incorporate those instructions with practical and fun uses for your application and you'll find a higher adoption and usage rate. Focus on what problems your app is solving for the user in the first place and make sure that you follow through on showing them how to do that.

As a side note, but just as important, it's useful to look at your application in this light as well. Does it empower a user to do want they want to do and quickly, or is it self-important?