Page from a manual, by Terry Freedman
When it comes to user documentation for a device or an application, what matters is that it’s useful to the intended user. I am sorry if that is a statement of the obvious, but quite often the writers of user docs suffer from the same disease as the people who write software:
“Hey, let’s chuck this in just in case it’s useful. It will only add one more feature to the 6,481 that are already there, of which people only use 20% anyway.”
Manual writers tend to suffer from that, in the form of:
“Hey, let’s just include instructions on how to achieve this via a command line user interface that most people, and even fewer teachers, are ever going to use — because I think it’s cool and important!”
I’m not saying you should not provide instructions for doing stuff through a command line environment, just that it has no place in the average user manual. Produce a separate, advanced one, instead.
Some user documentation is awful, but a lot is written well, but like the example just given is inappropriate. Like any piece of writing, it’s the end user/reader you should be writing for, not yourself.
I’ve written in more detail about this at Love the product, shame about the documentation, in which I suggest ways of making documentation useful rather than useless.
If you found this article interesting and useful, why not subscribe to my newsletter, Digital Education? It’s been going since the year 2000, and has news, views and reviews for Computing and ed tech teachers.