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.
Don’t forget about the documentation that has not been proofed or overlooked by people other than the authors. [That accounts for missing steps]
good point
It is always so difficult to do this right, but then you regret it afterwards.
Documentation isn’t always easy … but not having it always worse 🙂