there’s never enough documentation | there’s too much documentation

Documentation is vital. There’s never enough. And there’s always too much. In general, these are the areas I find documentation to fail:

Not Enough Too Much/Many
why-tos (instead of how-tos)

tutorials on things you need

architecture explanation

design philosophy “how we got here”

“why we are here”

future plans / roadmaps

deltas from standards recording

back-/cross-references to extant (even from other vendors / sources) documentation

extraneous verbiage – use terse verbosity

tutorials on things you don’t need / care about

discussion of non-core aspects of the product

how we used to do things

assumption of comprehension

plagiarism – ie, non-attribution of sources

braggadocio (not just excited) tone

different “voices” or styles

I have no quick-fixes. But I hope the above can help to address problems and help those responsible for documenting what they do to make it better. In the tech world, MSDN and developerWorks are the golden standards by which all other documentation should be compared … and to which [almost] all other documentation fails to aspire to.