Related link: http://www.oreillynet.com/pub/wlg/7479
Jacinta Richardson recently told me that “I personally would love to hear a talk about documenting existing projects or about rewriting documentation to aid the non-technical user (or both!).” So I think I’ll blog about it, to get my thoughts into order.
The first topic, of course, is ‘why?’ Why go to the effort? Why degeekify documentation at all?
There are perfectly good (and perfectly bad) documents out there on almost every technical topic, and we’ve all heard people assert that the programs themselves are documentation! The information is out there, why reorganise it?
Well, the short answer is to go see Damian Conway’s ‘Presentation Aikido’ speech.
Okay, it’s not very short. A shorter answer is to see this weblog OSCON 1.1: Presentation Aikido, particularly the line, “As Damian hammers home throughout the tutorial, your audience is giving you their most precious resource — their time — and that is a privilege that you should honor.”
Yes, those of your users who understand programming and know the language you’re programming in, could read the program to learn how to use it. Eventually.
The rest could do so after a week or two’s study of the language, and possibly a college degree in programming.
Or they could read the programmer’s documentation, or the program specifications. (And some user documentation reads very like a program specification.) This would take less time.
But wouldn’t it be easier, and more fun, for them to read something like this?
How to Change a Tyre
David Eddings had one of his characters say “All the books in the world won’t help you if they’re just piled up in a heap.”
I’d like to expand on that, and assert that “All the information in the world won’t help you if you can’t make sense of it.”
Do you have any documentation you read for pleasure?