The problems of over-documenting things

There is a certain school of thought in system documentation that believes, to stereotype things, that there is no such thing as being too explicit or having too many examples. Much of Sun's Solaris documentation makes a great example for this school.

Unfortunately, these people are wrong. There is such a thing as too much documentation, because having too much has a number of problems:

• your documentation becomes less and less readable, as the important things are buried under a flood of examples, cross references, and low level walkthroughs of how to do everything in sight. All of this is irrelevant clutter if I am trying to understand your system.

• your documentation becomes less useful as a reference work, because it is harder to skim it to extract the useful piece of information that I need to jog my memory.

• it is potentially insulting to your audience (especially if you are writing it for a specific local audience), because it implicitly assumes that the people reading it don't already know all of the basic things and have to be walked through everything in detail.

  (Even if people don't find it actively insulting, they are probably going to assume that your documentation is not aimed at them and they should go find something else.)

In short, belabouring the obvious takes up valuable space and people's limited time, distracts people, and can annoy them. (And that's what writing really detailed documentation is.)

In theory you can get around some of these problems by pushing your detailed examples and so on off to appendices. This avoids some of the problems but it still has the drawback that you are writing extra material, material that in my opinion is mostly pointless.

(This is not to say that examples and being 'obvious' are always bad things; per DocumentationAssumptions, sometimes they're necessary.)