{"id":1001,"date":"2016-01-28T17:06:00","date_gmt":"2016-01-28T08:06:00","guid":{"rendered":"http:\/\/n8finch.com\/?p=1001"},"modified":"2016-08-25T10:58:08","modified_gmt":"2016-08-25T01:58:08","slug":"documentation-as-a-discipline","status":"publish","type":"post","link":"https:\/\/n8finch2024.local\/documentation-as-a-discipline\/","title":{"rendered":"Documentation as a Discipline"},"content":{"rendered":"

A while ago, I read a\u00a0post from Tom McFarlin<\/a>\u00a0<\/strong>about keeping a change log. \u00a0I had actually just started a massive project and was scrambling to remember what I did the previous month and why. Also, we had promised to deliver technical documentation and user manuals. I figured that I would get through the project (which was due at the end of November)\u00a0and spend a day or two developing the documentation at that point.<\/p>\n

Bad idea. Here’s why…<\/p>\n

It’s Easy to Get Lost<\/h2>\n

In his article, Tom gives two primary reasons for keeping a changelog (and I would include\u00a0any documentation):<\/p>\n

    \n
  • Re-learning your work<\/li>\n
  • Identifying what went wrong<\/li>\n<\/ul>\n

    Even though I was up to my ears on this project and it was all I had thought about for a month, I still forgot and had to remember and re-learn what I had previously done. Data wasn’t where I had put it (actually it was, but I had changed the associated keys), I couldn’t remember certain steps for updating things, code snippets weren’t readily accessible, etc.<\/p>\n

    In short, I needed a quick review on everything I’d done. Upon reading this article, I immediately started a changelog and technical documentation in markdown documents. In the future, I think I will create these at the beginning of the project.<\/p>\n

    Writing Everything Out Is Very Clarifying<\/h2>\n

    When you have to verbally communicate what you’re doing (and even\u00a0why<\/em><\/strong> you’re doing it), thoughts, procedures and practices need to reach a level of clarity that the users (and my future self) can comprehend and act on.<\/p>\n

    Code snippets, plugin file contents, and rationale are all important for me to know and recall. I might have done something a certain way for the first time in my life, never to repeat. How would I remember how I did things and why without solid documentation?<\/p>\n

    It’s the Responsible Thing to Do<\/h2>\n

    What if I got hit by a bus tomorrow, or even worse, fired from this project?! (Ok, getting hit by a bus would be worse!)<\/p>\n

    Basically, if I’m not around, or have moved on professionally, who’s going to maintain the site? How will they know what to do? Documentation allows someone to come in and get up to speed quickly.<\/p>\n

    Also,\u00a0I will say, if I was in the zone, I could work for hours without getting up. However, if I didn’t immediately document what I was doing, my what<\/em><\/strong> and why<\/em><\/strong> of that stretch of decisions might have been lost. Immediately documenting what I did and why was very important.<\/p>\n

    \n

    Without disciplined documentation, you’re setting your client and yourself up for a big mess.<\/p>\n<\/blockquote>\n

    It’s a Nice Break from Coding<\/h2>\n

    While this isn’t always the case, documentation was a nice break from coding and building. I could relax a little bit and think, “I’ve just got to get the words on paper.”<\/p>\n

    It also seemed like a good reflection exercise. Several people end their day with reflections of what they did and gratitude. I felt like documentation was very similar to these exercises: a nice way to wind down and shelve the coding and building activities for the day.<\/p>\n

    I don’t think I’ll ever do another project again without starting at least some form of documentation.<\/p>\n

    ###<\/p>\n

    Peace,
    \nNate<\/strong><\/p>\n","protected":false},"excerpt":{"rendered":"

    A while ago, I read a\u00a0post from Tom McFarlin\u00a0about keeping a change log. \u00a0I had actually just started a massive project and was scrambling to remember what I did the previous month and why. Also, we had promised to deliver technical documentation and user manuals. I figured that I would get through the project (which […]<\/p>\n","protected":false},"author":1,"featured_media":1023,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_eb_attr":"","footnotes":""},"categories":[9,1,8],"tags":[],"yoast_head":"\nDocumentation as a Discipline | Nate Finch<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Documentation as a Discipline | Nate Finch\" \/>\n<meta property=\"og:description\" content=\"A while ago, I read a\u00a0post from Tom McFarlin\u00a0about keeping a change log. \u00a0I had actually just started a massive project and was scrambling to remember what I did the previous month and why. Also, we had promised to deliver technical documentation and user manuals. I figured that I would get through the project (which […]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/\" \/>\n<meta property=\"og:site_name\" content=\"Nate Finch\" \/>\n<meta property=\"article:published_time\" content=\"2016-01-28T08:06:00+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2016-08-25T01:58:08+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/n8finch-site.site.strattic.io\/wp-content\/uploads\/2020\/11\/documentation-as-a-discipline_snpyuy.jpg\" \/>\n\t<meta property=\"og:image:width\" content=\"650\" \/>\n\t<meta property=\"og:image:height\" content=\"433\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/jpeg\" \/>\n<meta name=\"author\" content=\"Nate\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:creator\" content=\"@n8finch\" \/>\n<meta name=\"twitter:site\" content=\"@n8finch\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Nate\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"3 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/#article\",\"isPartOf\":{\"@id\":\"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/\"},\"author\":{\"name\":\"Nate\",\"@id\":\"https:\/\/n8finch.local\/#\/schema\/person\/619068414583ca3c43bb135af49a47ce\"},\"headline\":\"Documentation as a Discipline\",\"datePublished\":\"2016-01-28T08:06:00+00:00\",\"dateModified\":\"2016-08-25T01:58:08+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/\"},\"wordCount\":566,\"commentCount\":0,\"publisher\":{\"@id\":\"https:\/\/n8finch.local\/#\/schema\/person\/619068414583ca3c43bb135af49a47ce\"},\"articleSection\":[\"20 Hours Ahead\",\"Blog\",\"Web Development\"],\"inLanguage\":\"en-US\"},{\"@type\":\"WebPage\",\"@id\":\"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/\",\"url\":\"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/\",\"name\":\"Documentation as a Discipline | Nate Finch\",\"isPartOf\":{\"@id\":\"https:\/\/n8finch.local\/#website\"},\"datePublished\":\"2016-01-28T08:06:00+00:00\",\"dateModified\":\"2016-08-25T01:58:08+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/n8finch.local\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Documentation as a Discipline\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/n8finch.local\/#website\",\"url\":\"https:\/\/n8finch.local\/\",\"name\":\"Nate Finch\",\"description\":\"All the things, keeping it clever...🤓\",\"publisher\":{\"@id\":\"https:\/\/n8finch.local\/#\/schema\/person\/619068414583ca3c43bb135af49a47ce\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/n8finch.local\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-US\"},{\"@type\":[\"Person\",\"Organization\"],\"@id\":\"https:\/\/n8finch.local\/#\/schema\/person\/619068414583ca3c43bb135af49a47ce\",\"name\":\"Nate\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/n8finch.local\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/n8finch2024.local\/wp-content\/uploads\/2020\/11\/nate-pic_ykd6mq.jpg\",\"contentUrl\":\"https:\/\/n8finch2024.local\/wp-content\/uploads\/2020\/11\/nate-pic_ykd6mq.jpg\",\"width\":796,\"height\":792,\"caption\":\"Nate\"},\"logo\":{\"@id\":\"https:\/\/n8finch.local\/#\/schema\/person\/image\/\"}}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Documentation as a Discipline | Nate Finch","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/","og_locale":"en_US","og_type":"article","og_title":"Documentation as a Discipline | Nate Finch","og_description":"A while ago, I read a\u00a0post from Tom McFarlin\u00a0about keeping a change log. \u00a0I had actually just started a massive project and was scrambling to remember what I did the previous month and why. Also, we had promised to deliver technical documentation and user manuals. I figured that I would get through the project (which […]","og_url":"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/","og_site_name":"Nate Finch","article_published_time":"2016-01-28T08:06:00+00:00","article_modified_time":"2016-08-25T01:58:08+00:00","og_image":[{"width":650,"height":433,"url":"https:\/\/n8finch-site.site.strattic.io\/wp-content\/uploads\/2020\/11\/documentation-as-a-discipline_snpyuy.jpg","type":"image\/jpeg"}],"author":"Nate","twitter_card":"summary_large_image","twitter_creator":"@n8finch","twitter_site":"@n8finch","twitter_misc":{"Written by":"Nate","Est. reading time":"3 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/#article","isPartOf":{"@id":"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/"},"author":{"name":"Nate","@id":"https:\/\/n8finch.local\/#\/schema\/person\/619068414583ca3c43bb135af49a47ce"},"headline":"Documentation as a Discipline","datePublished":"2016-01-28T08:06:00+00:00","dateModified":"2016-08-25T01:58:08+00:00","mainEntityOfPage":{"@id":"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/"},"wordCount":566,"commentCount":0,"publisher":{"@id":"https:\/\/n8finch.local\/#\/schema\/person\/619068414583ca3c43bb135af49a47ce"},"articleSection":["20 Hours Ahead","Blog","Web Development"],"inLanguage":"en-US"},{"@type":"WebPage","@id":"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/","url":"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/","name":"Documentation as a Discipline | Nate Finch","isPartOf":{"@id":"https:\/\/n8finch.local\/#website"},"datePublished":"2016-01-28T08:06:00+00:00","dateModified":"2016-08-25T01:58:08+00:00","breadcrumb":{"@id":"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/n8finch-site.site.strattic.io\/documentation-as-a-discipline\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/n8finch.local\/"},{"@type":"ListItem","position":2,"name":"Documentation as a Discipline"}]},{"@type":"WebSite","@id":"https:\/\/n8finch.local\/#website","url":"https:\/\/n8finch.local\/","name":"Nate Finch","description":"All the things, keeping it clever...🤓","publisher":{"@id":"https:\/\/n8finch.local\/#\/schema\/person\/619068414583ca3c43bb135af49a47ce"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/n8finch.local\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"en-US"},{"@type":["Person","Organization"],"@id":"https:\/\/n8finch.local\/#\/schema\/person\/619068414583ca3c43bb135af49a47ce","name":"Nate","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/n8finch.local\/#\/schema\/person\/image\/","url":"https:\/\/n8finch2024.local\/wp-content\/uploads\/2020\/11\/nate-pic_ykd6mq.jpg","contentUrl":"https:\/\/n8finch2024.local\/wp-content\/uploads\/2020\/11\/nate-pic_ykd6mq.jpg","width":796,"height":792,"caption":"Nate"},"logo":{"@id":"https:\/\/n8finch.local\/#\/schema\/person\/image\/"}}]}},"_links":{"self":[{"href":"https:\/\/n8finch2024.local\/wp-json\/wp\/v2\/posts\/1001"}],"collection":[{"href":"https:\/\/n8finch2024.local\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/n8finch2024.local\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/n8finch2024.local\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/n8finch2024.local\/wp-json\/wp\/v2\/comments?post=1001"}],"version-history":[{"count":3,"href":"https:\/\/n8finch2024.local\/wp-json\/wp\/v2\/posts\/1001\/revisions"}],"predecessor-version":[{"id":1130,"href":"https:\/\/n8finch2024.local\/wp-json\/wp\/v2\/posts\/1001\/revisions\/1130"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/n8finch2024.local\/wp-json\/wp\/v2\/media\/1023"}],"wp:attachment":[{"href":"https:\/\/n8finch2024.local\/wp-json\/wp\/v2\/media?parent=1001"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/n8finch2024.local\/wp-json\/wp\/v2\/categories?post=1001"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/n8finch2024.local\/wp-json\/wp\/v2\/tags?post=1001"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}