{"id":1517,"date":"2019-02-11T03:13:59","date_gmt":"2019-02-11T03:13:59","guid":{"rendered":"https:\/\/blog.hassler.ec\/wp\/?p=1517"},"modified":"2019-01-19T21:20:08","modified_gmt":"2019-01-19T21:20:08","slug":"good-and-bad-technical-documentation-examples","status":"publish","type":"post","link":"https:\/\/blog.hassler.ec\/wp\/2019\/02\/11\/good-and-bad-technical-documentation-examples\/","title":{"rendered":"Good and Bad Technical Documentation Examples"},"content":{"rendered":"

\n

Are your user manuals good<\/strong> or bad<\/strong>? Let\u2019s run them through our quick checklist. Don\u2019t get discouraged if it turns out to be not perfect, this article contains a lot of ideas to follow that can change your user manuals for the better!<\/p>\n

Lists<\/h3>\n

In bad<\/strong> user manuals, lists of steps for instructions are not-ordered. Simple bulleted lists are used instead. This is very inconvenient to follow such a list when you are trying to use some instruction.<\/p>\n

Good <\/strong>user manual always feature ordered lists of instructions. It works great for readers and support engineers as this makes it so much easier to refer to steps when they are numbered. Here\u2019s an article on using lists correctly in technical documents<\/a> that will help you avoid many common mistakes.<\/p>\n

Screenshots and Images<\/h3>\n

Bad <\/strong>technical documentation has few or next to no images in it. First, this just looks lazy. Second, it makes understanding harder for readers.<\/p>\n

Another way to ruin a help topic is to add screenshots\/images without proper text descriptions\u200a\u2014\u200athese are very annoying to decipher.<\/p>\n

\n
\n
<\/div>\n
<\/canvas><\/div>\n<\/div>\n<\/figure>\n

Good <\/strong>documentation has plenty of images. Any screenshot is always followed by some description. Also, two screenshots never appear next to each other without an individual capture.<\/p>\n

It is a good practice to keep in mind the image size (when we are talking about online documentation). Ideally, your images should be of decent quality, but quite light at the same time. Heavy images lead to slow page load and high traffic consumption.<\/p>\n

Delivery Speed<\/h3>\n
\n
\n
<\/div>\n
<\/canvas><\/div>\n<\/div>\n<\/figure>\n

Bad <\/strong>documentation takes a lot of time to be delivered. This can happen due to many factors including the absence of a help authoring tool. Online documentation tools<\/a> make content creation swift and easy.<\/p>\n

Good <\/strong>technical documentation is reusable and takes less time and effort to be created. Taking advantage of a HAT\u2019s functionality can be a game changer. Technical writing tools help to organize teamwork, reuse content with single-sourcing techniques, write help topics faster with powerful WYSIWYG editors.<\/p>\n

Consistency<\/h3>\n

Bad <\/strong>user manuals look and feel inconsistent. This happens because often many technical writers<\/a> can be working on the same project and this can lead to diversity in texts. Like, different terms can be used to describe similar processes, page layouts can look entirely different, etc.<\/p>\n

Good <\/strong>documentation teams have a style guide and a documentation plan<\/a>. These two are used by all team members, and they ensure there are no noticeable differences in style throughout the whole documentation project.<\/p>\n

Readability Score<\/h3>\n
\n
\n
<\/div>\n
<\/canvas><\/div>\n<\/div>\n<\/figure>\n

Bad <\/strong>user manuals are hard to read. You really need to put some effort to understand all the terms and break down long complex sentences. Terms are not explained, text contains just a few links\/references.<\/p>\n

Good <\/strong>user manuals are checked with readability score tools. This means that the content runs through different tests and it gets a readability score based on various algorithms (word length, sentence length, frequency of word usage, quantity of terms in a text). If the score is not satisfactory, user manuals are re-written.<\/p>\n

Conclusion<\/h3>\n

There are many differences between good and bad technical documentation. Often, the devil is in the details and smaller things like poor font choice or too many abbreviations and neologisms or even bad screenshot quality (we are not only talking about their resolution here) can put people off. Feel free to share your ideas on the topic in the comment section below\u200a\u2014\u200awhat bad technical documentation is like for you?<\/p>\n

Good luck with your technical writing!
\nClickHelp Team<\/a>
\nAuthor, host and deliver documentation across platforms and devices<\/p>\n

 <\/p>\n

 <\/p>\n

Source: https:\/\/medium.com\/level-up-web\/good-and-bad-technical-documentation-examples-bce3353cbc08<\/strong><\/a><\/p>\n

Written by<\/p>\n

\"Go<\/a><\/div>\n
\n

ClickHelp<\/a><\/h3>\n

ClickHelp – Professional Online Technical Writing Tool. Check it out: https:\/\/clickhelp.com\/online-documentation-tool\/<\/a><\/p>\n<\/div>\n

 <\/p>\n

\"Level<\/a><\/div>\n
\n

Level Up!<\/a><\/h3>\n

Stories for technical writers, web developers and web designers. It’s time to level up your skills!<\/p>\n<\/div>\n

 <\/p>\n

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

Are your user manuals good or bad? Let\u2019s run them through our quick checklist. Don\u2019t get discouraged if it turns out to be […]<\/p>\n","protected":false},"author":2,"featured_media":901,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"site-sidebar-layout":"default","site-content-layout":"","ast-site-content-layout":"default","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","theme-transparent-header-meta":"","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"default","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"footnotes":""},"categories":[12,128,39,78,21,105,40],"tags":[],"class_list":["post-1517","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-bloghassler-ec","category-clickhelp","category-escritores","category-google","category-productividad","category-teamwork","category-technical-writer"],"_links":{"self":[{"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/posts\/1517","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/comments?post=1517"}],"version-history":[{"count":2,"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/posts\/1517\/revisions"}],"predecessor-version":[{"id":1520,"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/posts\/1517\/revisions\/1520"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/media\/901"}],"wp:attachment":[{"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/media?parent=1517"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/categories?post=1517"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/tags?post=1517"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}