{"id":152,"date":"2016-06-28T14:41:32","date_gmt":"2016-06-28T14:41:32","guid":{"rendered":"http:\/\/bootstrap-it.com\/blog\/?p=152"},"modified":"2018-01-25T03:07:04","modified_gmt":"2018-01-25T03:07:04","slug":"why-is-so-much-enterprise-documentation-so-awful","status":"publish","type":"post","link":"https:\/\/bootstrap-it.com\/blog\/?p=152","title":{"rendered":"Why Is so Much Enterprise Documentation so Awful?"},"content":{"rendered":"
<\/a><\/a><\/a><\/a><\/a><\/div>

\"documentation-small\"I spend a very large portion of my professional workday reading through technology documentation. Perhaps “reading through” isn’t quite the right way to describe it. At this point, it’s more like quickly scanning menus, FAQs, and paragraph headings for\u00a0clues to where I can find the exact piece of information I’m after.\u00a0With some exceptions, this tends to be the case whether I’m just looking for a quick confirmation\u00a0of the right command line syntax or whether I’m trying to get my mind around a whole new technology.<\/p>\n

Web-based Technology Documentation: The art of underperformance<\/h3>\n

Now, I have no complaints with the people who provide detailed syntax guides and man pages – why should they\u00a0reformat their entire document\u00a0to highlight some obscure\u00a0detail for which I may\u00a0someday<\/em> come searching? But when I’m trying to introduce myself to a complicated software package – to figure out its purpose and primary\u00a0use-case – then it’s reasonable for me\u00a0to expect a relatively predictable and comfortable route to my goal. Instead, I often encounter a project home page with links to multiple targets with names like\u00a0“Getting Started,” “How to use…?” “Documentation” and, buried deeply under a few menu layers, “Quick Start Guide.”<\/p>\n

Often, the pages I’m sent to will be incomplete, apparently the victims of changed minds and budget overruns. Others will cover outdated\u00a0versions of the software that might easily have a feature set that’s significantly different than the latest version. Worse: the features might actually still exist but, between then and now, they’ve changed names and even icons.<\/p>\n

Even if we ignore the quality of the writing – something that\u00a0can be remarkably difficult and costly to control – and the intelligibility of individual documents,\u00a0there often seem to be significant version control and project management problems. I\u00a0can usually guess what\u00a0happened: some customers complained that they couldn’t figure out how to use the software, so management – unable to properly assess the current state of the documentation on their own – ordered the creation of a complete new set from scratch. The project starts, but about half way through, the key contributor either leaves the company or is distracted by other deadlines and demands.<\/p>\n

And there it sits until a few more customers complain that they, too, can’t figure out how to use the software. Rinse. Repeat.<\/p>\n

Is poor documentation always evil? Absolutely not. I’m often amazed at just how much some\u00a0open source projects manage to accomplish considering the limited resources they’re usually working with. And, in any case, as long as people (like me) aren’t volunteering to help out, we have no right to grumble.<\/p>\n

Is all documentation evil? Nope. While you could argue that there’s way too much of it, Amazon’s AWS maintains a magnificent documentation resource<\/a> that’s well-written, well-designed, and so well organized across the system that finding elements within any given page is predictable and fast. AWS isn’t the only success story out there, but it’s not exactly part of an overcrowded field, either.<\/p>\n

Technology Books: the art of overperformance<\/h3>\n

At the other end of the documentation continuum lie books.\u00a0Remember those? While I may not have purchased a tech\u00a0book for years, many thousands of other people do it all the time. In fact, at least in the short term, the technology publishing\u00a0industry seems remarkably healthy.<\/p>\n

The better\u00a0traditional publishers will subject a book proposal to very close analysis before concluding that the idea makes sense and that there are enough readers interested to make it worthwhile. Once the writing begins, they’ll throw\u00a0layers and layers of editors and reviewers at every stage of a book’s production. And when they’ve run out of editors, they’ll stage an editorial board review to make sure it wasn’t all a terrible mistake.<\/p>\n

That’s how my editors at Manning<\/a> work. And it’s also quite similar to the process I go through producing my video courses at Pluralsight<\/a>.<\/p>\n

When it’s done properly, the system creates checkpoints at the theme, style, chapter, and even paragraph levels, asking whether this element is needed, is presented as well as it can be, and will fit properly into the greater vision. These checkpoints make for great books, but they tend to be very expensive.<\/p>\n

Is it overdone? Sometimes. Is the full-blown multi-level editorial system going to be affordable for web-based documentation projects? Perhaps not always.<\/p>\n

But creating high-quality, readable, and well-organized documentation is a significant business need for many companies, so it would probably be a really good idea for them to at least submit what they’ve already got to a thorough audit by someone with experience, technical knowledge, and – most important of all – objectivity. The odds are, that will lead to a far more useful documentation product. And yes: documentation is also a product.<\/p>\n","protected":false},"excerpt":{"rendered":"

I spend a very large portion of my professional workday reading through technology documentation. Perhaps “reading through” isn’t quite the right way to describe it. At this point, it’s more like quickly scanning menus, FAQs, and paragraph headings for\u00a0clues to… Continue Reading →<\/span><\/a><\/p>\n","protected":false},"author":2,"featured_media":165,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-152","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-uncategorized"],"yoast_head":"\nWhy Is so Much Enterprise Documentation so Awful? - Bootstrap IT<\/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:\/\/bootstrap-it.com\/blog\/?p=152\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Why Is so Much Enterprise Documentation so Awful? - Bootstrap IT\" \/>\n<meta property=\"og:description\" content=\"I spend a very large portion of my professional workday reading through technology documentation. Perhaps “reading through” isn’t quite the right way to describe it. At this point, it’s more like quickly scanning menus, FAQs, and paragraph headings for\u00a0clues to… Continue Reading →\" \/>\n<meta property=\"og:url\" content=\"https:\/\/bootstrap-it.com\/blog\/?p=152\" \/>\n<meta property=\"og:site_name\" content=\"Bootstrap IT\" \/>\n<meta property=\"article:published_time\" content=\"2016-06-28T14:41:32+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2018-01-25T03:07:04+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/bootstrap-it.com\/blog\/wp-content\/uploads\/documentation.png\" \/>\n\t<meta property=\"og:image:width\" content=\"800\" \/>\n\t<meta property=\"og:image:height\" content=\"800\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/png\" \/>\n<meta name=\"author\" content=\"David Clinton\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:creator\" content=\"@davidbclinton\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"David Clinton\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"4 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/bootstrap-it.com\/blog\/?p=152\",\"url\":\"https:\/\/bootstrap-it.com\/blog\/?p=152\",\"name\":\"Why Is so Much Enterprise Documentation so Awful? - Bootstrap IT\",\"isPartOf\":{\"@id\":\"https:\/\/bootstrap-it.com\/blog\/#website\"},\"datePublished\":\"2016-06-28T14:41:32+00:00\",\"dateModified\":\"2018-01-25T03:07:04+00:00\",\"author\":{\"@id\":\"https:\/\/bootstrap-it.com\/blog\/#\/schema\/person\/2db6d8bce89bf20e8f06440c428abe68\"},\"breadcrumb\":{\"@id\":\"https:\/\/bootstrap-it.com\/blog\/?p=152#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/bootstrap-it.com\/blog\/?p=152\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/bootstrap-it.com\/blog\/?p=152#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/bootstrap-it.com\/blog\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Why Is so Much Enterprise Documentation so Awful?\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/bootstrap-it.com\/blog\/#website\",\"url\":\"https:\/\/bootstrap-it.com\/blog\/\",\"name\":\"Bootstrap IT\",\"description\":\"Learn technology using technology\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/bootstrap-it.com\/blog\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-US\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/bootstrap-it.com\/blog\/#\/schema\/person\/2db6d8bce89bf20e8f06440c428abe68\",\"name\":\"David Clinton\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/bootstrap-it.com\/blog\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/fa132defc2e7804e08ce17c4644b6f88c498d73ed8d4c9c72039189f90df1af8?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/fa132defc2e7804e08ce17c4644b6f88c498d73ed8d4c9c72039189f90df1af8?s=96&d=mm&r=g\",\"caption\":\"David Clinton\"},\"sameAs\":[\"http:\/\/bootstrap-it.com\/\",\"dbclinton\",\"https:\/\/twitter.com\/davidbclinton\"],\"url\":\"https:\/\/bootstrap-it.com\/blog\/?author=2\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Why Is so Much Enterprise Documentation so Awful? - Bootstrap IT","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:\/\/bootstrap-it.com\/blog\/?p=152","og_locale":"en_US","og_type":"article","og_title":"Why Is so Much Enterprise Documentation so Awful? - Bootstrap IT","og_description":"I spend a very large portion of my professional workday reading through technology documentation. Perhaps “reading through” isn’t quite the right way to describe it. At this point, it’s more like quickly scanning menus, FAQs, and paragraph headings for\u00a0clues to… Continue Reading →","og_url":"https:\/\/bootstrap-it.com\/blog\/?p=152","og_site_name":"Bootstrap IT","article_published_time":"2016-06-28T14:41:32+00:00","article_modified_time":"2018-01-25T03:07:04+00:00","og_image":[{"width":800,"height":800,"url":"https:\/\/bootstrap-it.com\/blog\/wp-content\/uploads\/documentation.png","type":"image\/png"}],"author":"David Clinton","twitter_card":"summary_large_image","twitter_creator":"@davidbclinton","twitter_misc":{"Written by":"David Clinton","Est. reading time":"4 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/bootstrap-it.com\/blog\/?p=152","url":"https:\/\/bootstrap-it.com\/blog\/?p=152","name":"Why Is so Much Enterprise Documentation so Awful? - Bootstrap IT","isPartOf":{"@id":"https:\/\/bootstrap-it.com\/blog\/#website"},"datePublished":"2016-06-28T14:41:32+00:00","dateModified":"2018-01-25T03:07:04+00:00","author":{"@id":"https:\/\/bootstrap-it.com\/blog\/#\/schema\/person\/2db6d8bce89bf20e8f06440c428abe68"},"breadcrumb":{"@id":"https:\/\/bootstrap-it.com\/blog\/?p=152#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/bootstrap-it.com\/blog\/?p=152"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/bootstrap-it.com\/blog\/?p=152#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/bootstrap-it.com\/blog"},{"@type":"ListItem","position":2,"name":"Why Is so Much Enterprise Documentation so Awful?"}]},{"@type":"WebSite","@id":"https:\/\/bootstrap-it.com\/blog\/#website","url":"https:\/\/bootstrap-it.com\/blog\/","name":"Bootstrap IT","description":"Learn technology using technology","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/bootstrap-it.com\/blog\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/bootstrap-it.com\/blog\/#\/schema\/person\/2db6d8bce89bf20e8f06440c428abe68","name":"David Clinton","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/bootstrap-it.com\/blog\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/fa132defc2e7804e08ce17c4644b6f88c498d73ed8d4c9c72039189f90df1af8?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/fa132defc2e7804e08ce17c4644b6f88c498d73ed8d4c9c72039189f90df1af8?s=96&d=mm&r=g","caption":"David Clinton"},"sameAs":["http:\/\/bootstrap-it.com\/","dbclinton","https:\/\/twitter.com\/davidbclinton"],"url":"https:\/\/bootstrap-it.com\/blog\/?author=2"}]}},"_links":{"self":[{"href":"https:\/\/bootstrap-it.com\/blog\/index.php?rest_route=\/wp\/v2\/posts\/152","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/bootstrap-it.com\/blog\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/bootstrap-it.com\/blog\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/bootstrap-it.com\/blog\/index.php?rest_route=\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/bootstrap-it.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=152"}],"version-history":[{"count":23,"href":"https:\/\/bootstrap-it.com\/blog\/index.php?rest_route=\/wp\/v2\/posts\/152\/revisions"}],"predecessor-version":[{"id":330,"href":"https:\/\/bootstrap-it.com\/blog\/index.php?rest_route=\/wp\/v2\/posts\/152\/revisions\/330"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/bootstrap-it.com\/blog\/index.php?rest_route=\/wp\/v2\/media\/165"}],"wp:attachment":[{"href":"https:\/\/bootstrap-it.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=152"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/bootstrap-it.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=152"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/bootstrap-it.com\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=152"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}