Arnt Gulbrandsen
About meAbout this blog

Too Much Documentation

This is a bit of a rant.

I claim that, for any single page in a documentation set, whether it's pages in a book, web pages on a documentation site or even unix man pages, one of these three cases holds:

Case 1: The page itself has some answers, and people who ask the questions the page answer are quickly directed there, and people who ask other questions don't waste their time reading the page.

Case 2: The page itself has some answers, but people who need those answers aren't quickly directed there, or people land there looking for something else.

Case 3: The page may or may not have answers, and noone ever looks at it while trying to find an answer.

If you don't have a question: Case 3. If you have one, but land on the wrong page: Case 2. If you have one, and land on the right page: Case 1.

In case 1, all is fine. In case 3, the page doesn't waste any user's time, so there isn't any problem. (I'm assuming that disk space is free. For text, that's very nearly true — the disk space to store this page costs €0.0000015 at the time of writing. CDs and bandwidth are also cheap.)

That leaves case 2.

In that case, the user doesn't get to the answering page. If the answer to the user's question is on page 40, and the user never looks at page 40, then page 40 cannot be the problem. The problem is quite likely that the index or table of contents is bad. Or perhaps the terminology is wrong — the user is looking up zucchini and there's documentation for courgettes.

Or the user gets to page 40, but the answer is elsewhere. Again, the real problem is on the page that misled the user to turn to page 40.

Is there too much documentation? Should any of the documentation be removed? In case 1 not — the part being considered is necessary and useful, and cannot be removed. In case 2 it's needed and the indexing should be improved. In case 3, it does no harm (apart from those €0.0000015).

Since the unread documentation does the user no harm, I say: There is never any reason to remove factually correct documentation.

The email that got me started on this talked about documentation being unnecessary, implying that if a part of the documentation is unnecessary, it is superfluous and it should be removed. The correct statement is that it can be removed.

If noone will ever ask a given question, its answer can be removed. But how can you know noone will ask the question? Don't you think the possibility to ask the question and get an answer is worth €0.0000015?