Skip to content

antipaucity

fighting the lack of good ideas

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

Posted on 11 October 201311 October 2013 By antipaucity 5 Comments on 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.

commentary, complaint, ideas, technical, work Tags:documentation

Post navigation

Previous Post: the value of face-to-face
Next Post: play a sucker to catch a sucker – seem dumber than your mark – law 21 – #48laws by robert greene

More Related Articles

helping a magpierss-powered site perform better personal
what level of abstraction is appropriate? commentary
turn on spf filtering with postfix and centos 7 technical
here seems like it would be perfect for pilots ideas
owncloud vs pydio – more diy cloud storage insights
is google killing our brains? commentary
October 2013
S M T W T F S
 12345
6789101112
13141516171819
20212223242526
2728293031  
« Sep   Nov »
  • Patrick Henry 23 March 1775
  • Reincarnation by Wallace McCrae (adapted by Warren Myers)
  • Famed was Beowulf
  • Fuzzy Wuzzy (anonymous)
  • One bright morning in the middle of the night (various)

Books

  • Debugging and Supporting Software Systems
  • Storage Series

External

  • Backblaze
  • Cirkul
  • Digital Ocean
  • Fundrise
  • Great Big Purple Sign
  • Password Generator
  • PayPal
  • Tech News Channel on Telegram
  • Wish List

Other Blogs

  • Abiding in Hesed
  • Chris Agocs
  • Eric Hydrick
  • Jay Loden
  • Paragraph
  • skh:tec
  • Tech News Channel on Telegram
  • Veritas Equitas

Profiles

  • LinkedIn
  • Server Fault
  • Stack Overflow
  • Super User
  • Telegram
  • Twitter

Resume

  • LinkedIn
  • Resume (PDF)

Services

  • Datente
  • IP check
  • Password Generator
  • Tech News Channel on Telegram

Support

  • Backblaze
  • Built Bar
  • Cirkul
  • Digital Ocean
  • Donations
  • Fundrise
  • PayPal
  • Robinhood
  • Wish List

Copyright © 2023 antipaucity.

Powered by PressBook Green WordPress theme