Does (system) documentation work?

OK, I promise this is the last entry on the Nurnberg funnel, after this I’ve worked it through my system…

In my entry on Nurnberg funnel and system development I wondered is system documentation actually works.  Well I missed one piece of evidence that it does work.  Go into your local bookstore, Waterstones, Borders, even Amazon online and look at the books on computing.  Specifically look at the technical books that describe things like programming languages, operating systems, APIs and the like.  If system documentation does not work how do we explain the existence of all these books?

After all, publishers are in the business of making money.  If these books did not work - i.e. did not help learning and transfer knowledge - then presumably nobody would buy them, there would be no profit in publishing them and consequently they wouldn't be taking up real-estate space in the book store.

So how do we explain these books if technical documentation doesn't work?

I don't have any figures on what is happening but here is my guess.

Firstly a whole load of this documentation does not work.  Many books get bought despite being bad.  Many more books are bad and simply don't get bought, publishers swallow the loss and pulp the books.  I would guess this category covers many many books.  Lets take a stab and say 40% of all technical books.

A second category of books do work and they work for exactly the reasons Carroll outlined in the Nurnberg funnel.  They are written along the lines of minimalism.  My guess it that a lot of those "For Dummies" and similar books fall into this category.  Still, this type of book represents a small percentage of all books.  Lets say 5% - probably an overstatement but it keeps the numbers easy.

OK, I still have 55% to account for - and I'm deliberately not saying if these are percentage of books sold or books published.

Next up I think there are some books which do not directly take on board the minimalist ideas but have a similar approach and work for similar reasons.  I'm specifically thinking here of patterns books like Design patterns and Pattern Languages of Program Design 5 (to which I was a contributor).

In part patterns are popular and accessible because they start with a problem and describe a solution.  This is a little like the task orientation that Carroll advocates.  I'm sure patterns books are not alone here but there aren't very many books in this category so lets just say another 5%.

This also starts to hint at another explanation and one which must account for many of the remaining 50% of books.  Simply minimalism is but one technique for creating documentation, it works particularly well in one field - user manuals - but it is not the only one.

For example I know of one other method, story telling.  This is usually advocated as a management or knowledge management activity to be conducted verbally.  (See books like The Springboard and Storytelling in Organizations). However there are technical books out there that take the same track. 

For example, I found the original version of Inside Windows NT quite story like.  Although perhaps this is a sign of how techno-geeky I was in the mid-late 1990's.  Somehow the second edition of the book never had the same plot or interest for me.

Less technical books about technical subjects are better examples of story telling.  Take The Soul of a New Machine for example.  This is a must read, I left it far too long before I read it but its right up there with The Mythical Man Month, Peopleware and The Psychology of Computer Programming if you want to know how software (and hardware) really get created.  But Soul of a New Machine is also a story, it can even be bedtime reading.

Books like these are more the exception than the rule so they are few and far between.  Lets say 1% are story books.

Another category is reference books like Charles Petzold’s Programming Windows.  I defy anyone to actually read this books cover to cover, you delve into when you have a specific problem or need to know some specific detail.  But reference books probably constitute a lot of the books written, say 20%.

That takes me to 71%.  I still can't account for 29% of books.  I give up.

The important thing is that people read books for different reasons.  Our motivation for reading one of these books will be different to the motivation for reading another.  That will change the way we approach buying and reading books. 

Which in a strange way brings us back to minimalism.  People use Petzold's books when they have a task to accomplish.  People pick them up under certain circumstances and like a Dummies book expect to get something specific from them.  But that doesn't mean all books should be written in the minimalist style.  Minimalism is just one of many styles.

So actually, we've come back to one of the re-occurring themes of this blog: know your customers, service their needs with a product that is designed to meet those needs. 

Products development doesn't end when the code is written, compiled and burnt onto a CD.  It has to include the documentation, service and support that is supplied with the products.  It also means ensuring that future product development can continue, whether through just-in-case documentation or just-in-time networks of people who know. 

Unfortunately obvious solutions – like big thick manuals - are not necessarily the best solutions.  We need to be on the look out for new solutions and new ideas.

And we need to understand the costs and benefits of all this.  This is difficult bit because so often we don't know the numbers and we can only speculate on what they are.  But somehow we need to put all of that together.