I see this as two questions: What is 'good' documentation?
...And: 'Why do users come to Stack Overflow, even when I can show them good documentation that answers their question'?
There's no short answer to either question, so please take a moment to read a long one. If you don't have the time, here's the very, very short answer to the first one:
Manuals and documentation in general are written for more than one audience, and often they must be 'split out' into separate documents.
The common failure modes are:
- Sometimes, users are reading the wrong one;
- Sometimes, users have been *given* the wrong one and have no way of knowing that the other ones exist;
- But, all too often, you have only provided one of them.
So what are 'The Documents' that constitute a good Manual?
I'm going to explain this using the example of a typical piece of commercial software, rather than for programming in general and the particular questions asked by developers on Stack Overflow because it allows me to lay out the principles and the categories of a good manual in a structured way.
Nevertheless, the principles of good documentation hold true for notepad.exe, or for the vast and complex world of Visual Studio for Enterprise; the differences lie in choosing which category of documentation needs to be prioritised, and how it should be presented.
And, of course, on recognising which developers count as beginners, 'occasional users', experts, and 'Support Manual' users in terms of how they need to use the documentation. This is not as easy as you think, and it is often done badly: you should ask yourself "Who was the intended audience for this documentation" before concluding that the reason it is useless, to you, is that the authors are useless.
You will still be correct in drawing this conclusion, more often than not: good technical authors are rare, and the role is not valued in most software houses.
So here's the basic documentation set for a moderately complex piece of software:
Getting Started:
- Congratulations on purchasing ACME software's latest product!
- Here's how to get it up and running;
- These are the three most common task you will perform, with a brief explanation and short set of screenshots;
- Where to get more information (links to help, an example of context-sensitive help, and a link to the full manual);
- Three 'cheat sheets' of menu paths and keyboard shortcuts for the common tasks.
There is a skill to generating the 'Getting Started' document: it's got to be short, relevant, and memorable.
For simple software, it is sometimes the only documentation that needs to be provided to the user.
If it isn't that simple, there are always going to be things that you missed, and problems that new users and owners run into at the very start, which you hadn't anticipated: you have to keep on top of this, keep talking to new users, and keep updating the 'Getting Started' guide.
Many vendor's don't.
There's also the problem of shipping software into a vast universe of (say) mobile devices, all of which are slightly different, and many of them will be out-of-date: in this case, there will be a need for separate 'Getting Started' help documentation. This, too, needs to be short, relevant, and memorable: a searchable 'Q&A' or FAQ page is probably best.
For much of the world's software, Stack Overflow is all of the searchable 'Q&A' in existence for someone getting started. Now there's no disgrace in The Stack being the best source of answers for some products - we're pretty damn' good! - but I have a very low opinion of vendors who are so bad that the 'Stack is the only source.
Stack Overflow is the first place that users will go when your documentation lists a short set of twee little 'troubleshooting' problems and doesn't provide a link labeled 'What to do next, if none of it works for you'.
If that's what the 'help' section of your 'Getting Started' guide looks like, please consider a new career contributing methane to a landfill site.
Onward, then, to The Big Document in 'The Documentation'...
The User Manual:
A user manual has three audiences:
- Beginners;
- Occasional Users;
- Experts or 'Power Users'.
There is a fourth item, for a 'non-audience' of very special users:
I say 'non-audience' because they probably won't read the manual at all, but they are still represented in the
'do not do this' information that protects you against legal liability.
In the first three cases, your User Manuals have to support two separate and distinct activities:
- Learning to use the application and exploring additional functions after mastering the basics (the 'Training Manual' function);
- Looking up answers to specific questions about the functions of the software (the 'Reference Manual' function).
These two functions aren't really compatible: if you can fit them into a single document at all, you're going to structure it in distinct sections.
Structuring your information is really the key to all of this: far fewer people would ever look for 'Read the manual!' information on Stack Overflow if the manual provided a structured way to both read and retrieve the things they need to know.
I can't offer any guidance on the overall structure of your document - that's got to reflect the way it's deployed and used - but I can give you a tactical hint:
If every point that the users need to know is structured into these three sections, you will succeed in writing Good Documentation for beginners and for expert users:
- A memorable, meaningful, discoverable heading;
- The easy explanation and easy instructions;
- The details and the difficult stuff, if anyone needs to know more than the easy stuff.
You'll notice that I've mentioned beginners and experienced or expert users there, but not the 'Occasionals'.
Note that occasional users aren't beginners: they are often experts at one particular thing! So how does documentation work for them?
They don't need to wade through the introductory material, over and over again; but they do need 'reminders' if tasks they are performing (say) four times a year for quarterly reporting have a lot of separate steps.
The point about reminders isn't just that they are brief and to the point: they have to be easy to find, or you're forcing the occasional users to plow through all the documentation anyway.
A hint: a user manual with 'cheat sheet' sections of bullet-point lists of actions are very, very good for this: someone will adopt one of these and print it out for their own team's 'occasional user' task if you've done this documentation well.
So we get back to the structure of your document: does it make sense to each type of user, and does it work as both a training and a reference manual?
That's The Big One: now for the complicated one...
The Support Manual:
I'm going to deal with this lightly because there are very few generalisations that can be applied to good support documentation.
But the basics are:
- An overview of how the software actually works;
- The location of the error-reporting and debugging tools;
- ...And a worked example of their use;
- An 'FAQ' of the most common user error reports with worked examples of their resolution;
- A suggested 'first line support' script...
- ...And a searchable wiki or Jira-like vendor page of support issues, with details that are good enough to constitute a 'worked example' of each reported issue was resolved or worked around.
Some vendors do this; and some don't.
Some vendors supply 'recipe' instructions on what to do, but are very reticent about explanations: they don't quite believe that user support is often provided by people with more technical knowledge than the users.
In fairness, some vendors provide user support from a low-cost helpdesk with significantly less technical knowledge than the users, or even the office furniture; and it is perfectly logical for them to provide support documentation in the form of animated GIFs with catchy music and a popup reminding their supervisor to administer a 'Good Boy!' doggy-chocolate reward at key points in the 'support' process.
But the better class of vendor does provide a detailed support manual aimed at a technical audience, and so should you: it's hard to do, because we're a demanding audience... But doing it well is a reflection of your courtesy to your fellow-professionals, and some of us are going to remember having to work with the support manual at your last employer, when you are being interviewed for your next job.
I am, of course, assuming that you did it superbly.
But, in all cases, Stack Overflow is still the 'go-to' destination for answers, even when better information is available from the 'RTFM' official source.
Here's why:
The essential concept of discoverability:
I don't need to point out that both the teaching and reference functions of a manual should be searchable - although the training will lean towards a 'start from the beginning' narrative for some products - but the reference section and the 'Support Issues' list should be
discoverable.
This means that it's not just possible to 'look up' details of the things that you know by name or keyword: 'looking up the details' means you know what they are, you know exactly what they are called, and you have a pretty good idea as to where the information is already.
If you know all that already, great, but...
Discoverability is about finding out what it's called and where it is
...Yes, even if you're from a different technical background to the authors of the document.
Example: "Oh, I can see that I need the word 'dimension' to do this, not 'table'..."
Counter-example: "Stooopid newbies are expected to know that we call this 'a dimension' and they need to spend an afternoon reading the training manual if they don't"
So the short answer to your second question is:
Stack Overflow has discoverability.
You can discover answers here that you won't find on other sites, even in the 'official' documentation, because unlinked information left as 'look it up if you know exactly what it is and where' isn't 'documentation'; it's a digital sarcophagus.
And if you can't discover it by Googling into the vendor sites, the 'Stack provides the ultimate discovery tool: asking people who actually know.