{"id":3261,"date":"2018-01-22T10:17:38","date_gmt":"2018-01-22T15:17:38","guid":{"rendered":"https:\/\/antipaucity.com\/?p=3261"},"modified":"2018-01-22T10:17:38","modified_gmt":"2018-01-22T15:17:38","slug":"document-what-didnt-work","status":"publish","type":"post","link":"https:\/\/merikebi.warrenmyers.com\/?p=3261","title":{"rendered":"document what didn&#8217;t work"},"content":{"rendered":"<p>In a recent episode of <a href=\"https:\/\/wiki.securityweekly.com\/Episode544\">Paul&#8217;s Security Weekly<\/a>, an off-hand comment was made about documentation: you shouldn&#8217;t\u00a0<em>merely<\/em> document what\u00a0<strong>to<\/strong> do, nor even\u00a0<strong>why<\/strong>, but also what you tried that\u00a0<strong>didn&#8217;t work<\/strong> (ie, <a href=\"https:\/\/antipaucity.com\/2013\/10\/09\/new-documentation-should-always-augment-the-status-quo\/#.WmX_xZM-fgo\">augment the status\u00a0quo<\/a>).<\/p>\n<p>The upshot being, to save <a href=\"https:\/\/antipaucity.com\/2013\/02\/10\/organizational-knowledge-capture-retention-and-dissemination\/#.WmYGvZM-fgo\">whomever<\/a> comes to this note next (<em>especially if it turns out to be yourself<\/em>)\u00a0<a href=\"https:\/\/antipaucity.com\/2013\/10\/11\/theres-never-enough-documentation-theres-too-much-documentation\/#.WmX_85M-fgo\">effort<\/a> you spent that was in vain.<\/p>\n<p>This is similar to a famous\u00a0<a href=\"https:\/\/www.goodreads.com\/quotes\/8287-i-have-not-failed-i-ve-just-found-10-000-ways-that\">quote<\/a> attributed to Edison,<\/p>\n<blockquote><p>I have not failed. I&#8217;ve just found 10,000 ways that won&#8217;t work.<\/p><\/blockquote>\n<p>In light of my recommended, preferred\u00a0practice and policy of &#8220;<a href=\"https:\/\/cnx.org\/contents\/31arWXa5@4\/Submitting-Bug-Reports\">terse verbosity<\/a>&#8220;, I would strongly suggest\u00a0<em><strong>not<\/strong><\/em> placing the &#8220;doesn&#8217;t work&#8221; in-line, typically. Instead, put footnotes, an appendix, etc. But always<\/p>\n<blockquote><p>explain everything you did, but use bullet points if possible, rather than prose form<\/p><\/blockquote>\n<p>Loads of other goodies in that episode, too &#8211; but this one jumped-out as applicable to everyone.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>In a recent episode of Paul&#8217;s Security Weekly, an off-hand comment was made about documentation: you shouldn&#8217;t\u00a0merely document what\u00a0to do, nor even\u00a0why, but also what you tried that\u00a0didn&#8217;t work (ie, augment the status\u00a0quo). The upshot being, to save whomever comes to this note next (especially if it turns out to be yourself)\u00a0effort you spent that &hellip;<br \/><a href=\"https:\/\/merikebi.warrenmyers.com\/?p=3261\" class=\"more-link pen_button pen_element_default pen_icon_arrow_double\">Continue reading <span class=\"screen-reader-text\">document what didn&#8217;t work<\/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":[22,23],"tags":[251],"keyring_services":[],"class_list":["post-3261","post","type-post","status-publish","format-standard","hentry","category-ideas","category-insights","tag-documentation"],"jetpack_sharing_enabled":true,"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=\/wp\/v2\/posts\/3261","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=3261"}],"version-history":[{"count":0,"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=\/wp\/v2\/posts\/3261\/revisions"}],"wp:attachment":[{"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=3261"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=3261"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=3261"},{"taxonomy":"keyring_services","embeddable":true,"href":"https:\/\/merikebi.warrenmyers.com\/index.php?rest_route=%2Fwp%2Fv2%2Fkeyring_services&post=3261"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}