The Documentation

[John Tregea]

Hi Docu friends,

I have been reading the persistant and recurring thread about Rev documentation for a couple of years now. It brings to mind what a good friend of mine said about human communication (she is a writer). When a communication tool (of any sort) is done properly, with a real attention to what people need to get out of it and who those people are, they will keep coming back to the tool over and over again. They won't even know why, they will just keep using it. A well structured street directory, a good DVD menu system, a good piece of software, a good manual.

I have a memory that the HyperCard documentation was written by a team of professional, technical writers. Maybe that is why when we look at it, we can still connect to what was being communicated. For me, Dan Shafer's Hypertalk book was the best technical reference I had ever used, for any software. It gave me what I needed when I needed it, and it made me laugh along the way. (Thanks Dan)

I am not a writer, I try and build good software with an attention to many explicit and implicit lessons I have learnt about people (and their needs when using software) over more than 20 years of programming (mostly on the Mac platform). The documentation is not going to get better without someone that is a real writer/communicator attending to it. Blogs are fine in a particular context, but for me, they only provide fragmentary glimpses of larger structures. To gain the (critical) big picture of an architecture, I love to hold the written work in my hands and connect to large ideas as I learn the detail.

One of the particular challenges in software documentation (and boy have I experienced this) is that you have to know what something is called before you can find it. That is often the frustation, not that the information is missing, but because I call it something else, I cannot access it. In the case of Rev Docs, I have a frame of reference from many years of HyperCard and SuperCard programming, so it isn't causing me that kind of pain. However, from the persistency of this thread (and other before it) I am not a representative sampling of current Rev users.

A product like Revolution means so many different things to so many different (Types of) people, it is no wonder that the documentation is not connecting with various groups of us... Effective writing is a disciple that takes MANY years to learn. To be able to do it for such a disparate audience takes a master writer.

Regards

John T