{"id":2130,"date":"2013-10-11T08:33:14","date_gmt":"2013-10-11T12:33:14","guid":{"rendered":"http:\/\/antipaucity.com\/?p=2130"},"modified":"2013-10-11T08:33:14","modified_gmt":"2013-10-11T12:33:14","slug":"theres-never-enough-documentation-theres-too-much-documentation","status":"publish","type":"post","link":"https:\/\/merikebi.warrenmyers.com\/?p=2130","title":{"rendered":"there&#8217;s never enough documentation | there&#8217;s too much documentation"},"content":{"rendered":"<p><a href=\"http:\/\/antipaucity.com\/2013\/02\/10\/organizational-knowledge-capture-retention-and-dissemination\/#.Uk23JYaqm3I\">Documentation<\/a> is vital. There&#8217;s never enough. And there&#8217;s always too much. In general, these are the areas I find documentation to fail:<\/p>\n<table width=\"90%\" align=\"center\">\n<tbody>\n<tr align=\"center\" valign=\"\">\n<td width=\"50%\"><strong>Not Enough<\/strong><\/td>\n<td width=\"50%\"><strong>Too Much\/Many<\/strong><\/td>\n<\/tr>\n<tr align=\"center\" valign=\"top\">\n<td>why-tos (instead of how-tos) <\/p>\n<p>tutorials on things you need<\/p>\n<p>architecture explanation<\/p>\n<p>design philosophy &#8220;how we got here&#8221;<\/p>\n<p>&#8220;why we are here&#8221;<\/p>\n<p>future plans \/ roadmaps<\/p>\n<p><a href=\"http:\/\/antipaucity.com\/2013\/10\/09\/new-documentation-should-always-augment-the-status-quo\/#.Uk25Aoaqm3I\">deltas<\/a> from standards recording<\/p>\n<p>back-\/cross-references to extant (even from other vendors \/ sources) documentation<\/td>\n<td>extraneous verbiage &#8211; use <a href=\"http:\/\/cnx.org\/content\/m40790\/latest\">terse verbosity<\/a><\/p>\n<p>tutorials on things you don&#8217;t need \/ care about<\/p>\n<p>discussion of non-core aspects of the product<\/p>\n<p>how we used to do things<\/p>\n<p>assumption of comprehension<\/p>\n<p><a href=\"http:\/\/antipaucity.com\/2006\/10\/31\/is-plagiarism-really-so-bad\/#.Uk27lYaqm3I\">plagiarism<\/a> &#8211; ie, non-attribution of sources<\/p>\n<p>braggadocio (not just excited) tone<\/p>\n<p>different &#8220;voices&#8221; or styles<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>I have no quick-fixes. But I hope the above can help to address problems and help those <a href=\"http:\/\/antipaucity.com\/2011\/09\/20\/technical-career-development\/#.Uk27Zoaqm3I\">responsible<\/a> for documenting what they do to make it better. In the tech world, <a href=\"http:\/\/msdn.microsoft.com\">MSDN<\/a> and <a href=\"http:\/\/www.ibm.com\/developerworks\">developerWorks<\/a> are the golden standards by which all other documentation should be compared &#8230; and to which [almost] all other documentation fails to aspire to.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Documentation is vital. There&#8217;s never enough. And there&#8217;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 &#8220;how we got here&#8221; &#8220;why we are here&#8221; future plans \/ roadmaps deltas from standards recording &hellip;<br \/><a href=\"https:\/\/merikebi.warrenmyers.com\/?p=2130\" class=\"more-link pen_button pen_element_default pen_icon_arrow_double\">Continue reading <span class=\"screen-reader-text\">there&#8217;s never enough documentation | there&#8217;s too much documentation<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_hide_featured_image":false,"_jetpack_featured_image_duplicate_dismissed":0,"_jetpack_feature_clip_id":0,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_post_was_ever_published":false},"categories":[7,8,22,41,48],"tags":[251],"keyring_services":[],"class_list":["post-2130","post","type-post","status-publish","format-standard","hentry","category-commentary","category-complaint","category-ideas","category-technical","category-work","tag-documentation"],"jetpack_sharing_enabled":true,"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=\/wp\/v2\/posts\/2130","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=2130"}],"version-history":[{"count":0,"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=\/wp\/v2\/posts\/2130\/revisions"}],"wp:attachment":[{"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=2130"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=2130"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=2130"},{"taxonomy":"keyring_services","embeddable":true,"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=%2Fwp%2Fv2%2Fkeyring_services&post=2130"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}