I am looking for (common / abstract) templates and examples for the (end user) documentation of software. I especially need something for an "Installation Guide", an "Operation Guide" (operation / service / administration of the software), "User Guide" and "training documents". I have googled around, haven't found usable resources. I am also looking for design guidlines.
3 Answers
It's a big surprise to me, but Microsoft has finally begun to make good, useful, readable docs available. They live in MSDN and they might give you a handle on how good docs are organized. For example, the section on DLLs is a good one, I think.
And then you can start here at the top level.
The best I have found is tutorials/stories rather than encyclopedias for end user application docs - as opposed to library docs.
Pick some of the most common procedures and detail them step-step.
This is much more useful than the docs which just mirror the online help, which is full of cut-paste entries like "this is the blah button, it activates the blah function"
-
-
@Karlphilip - sorry? It wasn't a very detailed answer but it's a useful point May 4, 2011 at 18:50
-
@Karlphilip - A language difference. In English "you are all over the place" means your work is unorganised/random/crazy - thought you meant the answer was bad. May 4, 2011 at 18:57
I agree with @SnOrfus: look around for a good example and copy the template.
You know already that almost all end-user documentation just sucks; it's so, so bad: wordy, lots of extraneous BS, full of weasel words -- "it is recommended that," "the user is urged to," all crap like that. Just 90% pure hooey. And, by the way, remember that all of these so-called "user guides" are around 1200 pages long and cost $89.95.
There surely are a few good examples around, though. Kernighan and Ritchie, C Programming Language is the best example of a good end-user doc that I know of. It's short; it uses normal, everyday words; it's complete; it's correct. A beautiful work of art, in my opinion, that fits comfortably in 256 pages (first edition).
A good forum for this question is the writers' group on StackExchange. You'll find discussions of end-user technical docs over there sometimes.