{"id":1174,"date":"2015-07-20T14:06:00","date_gmt":"2015-07-20T14:06:00","guid":{"rendered":"https:\/\/ee.yelkdev.site\/?p=1174"},"modified":"2023-09-22T17:50:17","modified_gmt":"2023-09-22T16:50:17","slug":"agile-documentation","status":"publish","type":"post","link":"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/","title":{"rendered":"Agile Documentation"},"content":{"rendered":"

Every successful multi-year software project that I\u2019ve ever seen has had some sort of documentation.<\/p>\n

Whether it\u2019s a user manual, deployment guide, sample usage code, wiki, a run book for operations, release notes, javadoc, usage documentation for a REST API, or something else, there\u2019s always some sort of documentation somewhere.<\/p>\n

My views on documentation for software projects are roughly in line with the agile manifesto<\/a>, which states \u201c[we value] working software over comprehensive documentation\u201d. This seems to be a very popular point of view in the agile community, if only because many developers would rather not write documentation in the first place. In general, with documentation (as with code), less is more.<\/p>\n

Unfortunately, \u201cless\u201d usually doesn\u2019t mean \u201cnone\u201d. The truth is that other developers, operations teams, and architects almost always need at least some documentation. This is especially true for a consultancy like Equal Experts, because people will need this information when we\u2019re gone.<\/p>\n

And all forms of documentation have the same key weakness: they need to be maintained and kept up to date. Documentation that isn\u2019t actively maintained is often worse than no documentation at all \u2014 many agile developers have had to recite the phrase \u201cdocumentation lies\u201d so often that it becomes a mantra.<\/p>\n

In order to be successful, your project needs documentation, and you don\u2019t want to end up accidentally lying to your users, so this documentation will need to be kept accurate and up to date over time. How do you do this without a painful manual review1<\/sup><\/a>\u00a0stage as part of every release? This is especially important when you practice continuous delivery: reviewing documentation for each release when you release several times a day adds so much overhead that it\u2019s basically impossible.<\/p>\n

One strategy I like for keeping documentation accurate and up to date is to have the continuous integration process automatically verify as much of that documentation for you as it possibly can:<\/p>\n

    \n
  1. If your project has javadoc, make javadoc generation part of your CI build, so that referencing a parameter that doesn\u2019t exist in javadoc causes your build to fail.<\/li>\n
  2. Does your documentation have examples or sample code? Execute them as part of your build, and (automatically) check that each one still works, and still emits the expected results.<\/li>\n
  3. Automatically generate as much of your documentation as possible. For example, generate REST API documentation from source code annotations.<\/li>\n
  4. Use libraries and patterns (Such as our own opslogger library<\/a>) that make it easier to automatically generate documentation.<\/li>\n<\/ol>\n

    This tactic can help with heavy handed technical change management requirements as well. Need a detailed change request with every release to keep corporate operations happy? Automatically generate it from your git logs and issue management system. I was once on a team where we built a system that automatically compiled the list of JIRA issues that had been fixed since the last deployment. It was really simple (just a text file with JIRA issues and CI build numbers checked into git, really), but it made our operations team happy, and once we had it running it took us almost no effort at all to maintain.<\/p>\n

    In general, quality assurance for documentation (and make no mistake, that\u2019s what documentation maintenance is) is just like all other forms of agile quality assurance: automate as much of it as you possibly can. You\u2019ll find that the upfront investment in automation pays for itself, and then some.<\/p>\n

    \n

    1<\/sup><\/a>\u00a0pun intended.<\/p>\n","protected":false},"excerpt":{"rendered":"

    Every successful multi-year software project that I\u2019ve ever seen has had some sort of documentation. Whether it\u2019s a user manual, deployment guide, sample usage code, wiki, a run book for operations, release notes, javadoc, usage documentation for a REST API, or something else, there\u2019s always some sort of documentation somewhere. My views on documentation for […]<\/p>\n","protected":false},"author":2,"featured_media":1180,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"content-type":"","inline_featured_image":false,"footnotes":""},"categories":[3],"tags":[],"location":[397],"class_list":["post-1174","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-tech-focus"],"acf":[],"yoast_head":"\nAgile Documentation | Equal Experts<\/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:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/\" \/>\n<meta property=\"og:locale\" content=\"en_GB\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Agile Documentation\" \/>\n<meta property=\"og:description\" content=\"Every successful multi-year software project that I\u2019ve ever seen has had some sort of documentation. Whether it\u2019s a user manual, deployment guide, sample usage code, wiki, a run book for operations, release notes, javadoc, usage documentation for a REST API, or something else, there\u2019s always some sort of documentation somewhere. My views on documentation for […]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/\" \/>\n<meta property=\"og:site_name\" content=\"Equal Experts\" \/>\n<meta property=\"article:published_time\" content=\"2015-07-20T14:06:00+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2023-09-22T16:50:17+00:00\" \/>\n<meta name=\"author\" content=\"dorightdigital\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:creator\" content=\"@EqualExperts\" \/>\n<meta name=\"twitter:site\" content=\"@EqualExperts\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"dorightdigital\" \/>\n\t<meta name=\"twitter:label2\" content=\"Estimated 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:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#article\",\"isPartOf\":{\"@id\":\"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/\"},\"author\":{\"name\":\"dorightdigital\",\"@id\":\"https:\/\/www.equalexperts.com\/#\/schema\/person\/3faccba812b830c6efa9053ecb9d231a\"},\"headline\":\"Agile Documentation\",\"datePublished\":\"2015-07-20T14:06:00+00:00\",\"dateModified\":\"2023-09-22T16:50:17+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/\"},\"wordCount\":581,\"commentCount\":0,\"publisher\":{\"@id\":\"https:\/\/www.equalexperts.com\/#organization\"},\"image\":{\"@id\":\"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#primaryimage\"},\"thumbnailUrl\":\"\",\"articleSection\":[\"Tech Focus\"],\"inLanguage\":\"en-GB\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/\",\"url\":\"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/\",\"name\":\"Agile Documentation | Equal Experts\",\"isPartOf\":{\"@id\":\"https:\/\/www.equalexperts.com\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#primaryimage\"},\"image\":{\"@id\":\"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#primaryimage\"},\"thumbnailUrl\":\"\",\"datePublished\":\"2015-07-20T14:06:00+00:00\",\"dateModified\":\"2023-09-22T16:50:17+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#breadcrumb\"},\"inLanguage\":\"en-GB\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-GB\",\"@id\":\"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#primaryimage\",\"url\":\"\",\"contentUrl\":\"\"},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/www.equalexperts.com\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Agile Documentation\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/www.equalexperts.com\/#website\",\"url\":\"https:\/\/www.equalexperts.com\/\",\"name\":\"Equal Experts\",\"description\":\"Making Software. Better.\",\"publisher\":{\"@id\":\"https:\/\/www.equalexperts.com\/#organization\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/www.equalexperts.com\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-GB\"},{\"@type\":\"Organization\",\"@id\":\"https:\/\/www.equalexperts.com\/#organization\",\"name\":\"Equal Experts\",\"url\":\"https:\/\/www.equalexperts.com\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-GB\",\"@id\":\"https:\/\/www.equalexperts.com\/#\/schema\/logo\/image\/\",\"url\":\"https:\/\/www.equalexperts.com\/wp-content\/uploads\/2018\/08\/Equal_Experts_Logo_CMYK_Colour.jpg\",\"contentUrl\":\"https:\/\/www.equalexperts.com\/wp-content\/uploads\/2018\/08\/Equal_Experts_Logo_CMYK_Colour.jpg\",\"width\":719,\"height\":340,\"caption\":\"Equal Experts\"},\"image\":{\"@id\":\"https:\/\/www.equalexperts.com\/#\/schema\/logo\/image\/\"},\"sameAs\":[\"https:\/\/x.com\/EqualExperts\",\"https:\/\/www.linkedin.com\/company\/equal-experts\/?viewAsMember=true\"]},{\"@type\":\"Person\",\"@id\":\"https:\/\/www.equalexperts.com\/#\/schema\/person\/3faccba812b830c6efa9053ecb9d231a\",\"name\":\"dorightdigital\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-GB\",\"@id\":\"https:\/\/www.equalexperts.com\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/5fc44582a07d3eba2d5f99cc09e716f515d82ed73286ecda5e9db6a056dceed6?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/5fc44582a07d3eba2d5f99cc09e716f515d82ed73286ecda5e9db6a056dceed6?s=96&d=mm&r=g\",\"caption\":\"dorightdigital\"},\"sameAs\":[\"http:\/\/dorightdigital.wpengine.com\"]}]}<\/script>\n<!-- \/ Yoast SEO Premium plugin. -->","yoast_head_json":{"title":"Agile Documentation | Equal Experts","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:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/","og_locale":"en_GB","og_type":"article","og_title":"Agile Documentation","og_description":"Every successful multi-year software project that I\u2019ve ever seen has had some sort of documentation. Whether it\u2019s a user manual, deployment guide, sample usage code, wiki, a run book for operations, release notes, javadoc, usage documentation for a REST API, or something else, there\u2019s always some sort of documentation somewhere. My views on documentation for […]","og_url":"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/","og_site_name":"Equal Experts","article_published_time":"2015-07-20T14:06:00+00:00","article_modified_time":"2023-09-22T16:50:17+00:00","author":"dorightdigital","twitter_card":"summary_large_image","twitter_creator":"@EqualExperts","twitter_site":"@EqualExperts","twitter_misc":{"Written by":"dorightdigital","Estimated reading time":"3 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#article","isPartOf":{"@id":"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/"},"author":{"name":"dorightdigital","@id":"https:\/\/www.equalexperts.com\/#\/schema\/person\/3faccba812b830c6efa9053ecb9d231a"},"headline":"Agile Documentation","datePublished":"2015-07-20T14:06:00+00:00","dateModified":"2023-09-22T16:50:17+00:00","mainEntityOfPage":{"@id":"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/"},"wordCount":581,"commentCount":0,"publisher":{"@id":"https:\/\/www.equalexperts.com\/#organization"},"image":{"@id":"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#primaryimage"},"thumbnailUrl":"","articleSection":["Tech Focus"],"inLanguage":"en-GB","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#respond"]}]},{"@type":"WebPage","@id":"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/","url":"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/","name":"Agile Documentation | Equal Experts","isPartOf":{"@id":"https:\/\/www.equalexperts.com\/#website"},"primaryImageOfPage":{"@id":"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#primaryimage"},"image":{"@id":"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#primaryimage"},"thumbnailUrl":"","datePublished":"2015-07-20T14:06:00+00:00","dateModified":"2023-09-22T16:50:17+00:00","breadcrumb":{"@id":"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#breadcrumb"},"inLanguage":"en-GB","potentialAction":[{"@type":"ReadAction","target":["https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/"]}]},{"@type":"ImageObject","inLanguage":"en-GB","@id":"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#primaryimage","url":"","contentUrl":""},{"@type":"BreadcrumbList","@id":"https:\/\/www.equalexperts.com\/blog\/tech-focus\/agile-documentation\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/www.equalexperts.com\/"},{"@type":"ListItem","position":2,"name":"Agile Documentation"}]},{"@type":"WebSite","@id":"https:\/\/www.equalexperts.com\/#website","url":"https:\/\/www.equalexperts.com\/","name":"Equal Experts","description":"Making Software. Better.","publisher":{"@id":"https:\/\/www.equalexperts.com\/#organization"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/www.equalexperts.com\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-GB"},{"@type":"Organization","@id":"https:\/\/www.equalexperts.com\/#organization","name":"Equal Experts","url":"https:\/\/www.equalexperts.com\/","logo":{"@type":"ImageObject","inLanguage":"en-GB","@id":"https:\/\/www.equalexperts.com\/#\/schema\/logo\/image\/","url":"https:\/\/www.equalexperts.com\/wp-content\/uploads\/2018\/08\/Equal_Experts_Logo_CMYK_Colour.jpg","contentUrl":"https:\/\/www.equalexperts.com\/wp-content\/uploads\/2018\/08\/Equal_Experts_Logo_CMYK_Colour.jpg","width":719,"height":340,"caption":"Equal Experts"},"image":{"@id":"https:\/\/www.equalexperts.com\/#\/schema\/logo\/image\/"},"sameAs":["https:\/\/x.com\/EqualExperts","https:\/\/www.linkedin.com\/company\/equal-experts\/?viewAsMember=true"]},{"@type":"Person","@id":"https:\/\/www.equalexperts.com\/#\/schema\/person\/3faccba812b830c6efa9053ecb9d231a","name":"dorightdigital","image":{"@type":"ImageObject","inLanguage":"en-GB","@id":"https:\/\/www.equalexperts.com\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/5fc44582a07d3eba2d5f99cc09e716f515d82ed73286ecda5e9db6a056dceed6?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/5fc44582a07d3eba2d5f99cc09e716f515d82ed73286ecda5e9db6a056dceed6?s=96&d=mm&r=g","caption":"dorightdigital"},"sameAs":["http:\/\/dorightdigital.wpengine.com"]}]}},"_links":{"self":[{"href":"https:\/\/www.equalexperts.com\/wp-json\/wp\/v2\/posts\/1174","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.equalexperts.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.equalexperts.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.equalexperts.com\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.equalexperts.com\/wp-json\/wp\/v2\/comments?post=1174"}],"version-history":[{"count":0,"href":"https:\/\/www.equalexperts.com\/wp-json\/wp\/v2\/posts\/1174\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.equalexperts.com\/wp-json\/"}],"wp:attachment":[{"href":"https:\/\/www.equalexperts.com\/wp-json\/wp\/v2\/media?parent=1174"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.equalexperts.com\/wp-json\/wp\/v2\/categories?post=1174"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.equalexperts.com\/wp-json\/wp\/v2\/tags?post=1174"},{"taxonomy":"location","embeddable":true,"href":"https:\/\/www.equalexperts.com\/wp-json\/wp\/v2\/location?post=1174"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}