{"id":2833,"date":"2020-03-08T04:21:38","date_gmt":"2020-03-08T04:21:38","guid":{"rendered":"https:\/\/blog.hassler.ec\/wp\/?p=2833"},"modified":"2020-02-21T03:24:02","modified_gmt":"2020-02-21T03:24:02","slug":"common-mistakes-in-technical-writing","status":"publish","type":"post","link":"https:\/\/blog.hassler.ec\/wp\/2020\/03\/08\/common-mistakes-in-technical-writing\/","title":{"rendered":"Common Mistakes in Technical Writing"},"content":{"rendered":"
\n
\n
\n
\n
<\/div>\n<\/div>\n<\/div>\n<\/div>\n
\n
\n
\n
<\/div>\n<\/div>\n<\/figure>\n<\/div>\n
\n
\n

Let\u2019s have a look at the most common mistakes in technical writing, so you\u2019ll avoid them. I\u2019ll also provide you with tips that help you fix them.<\/p>\n

Poor Structure<\/h1>\n

Many technical documents confuse readers, so they can\u2019t achieve their goals because they just can\u2019t find the necessary topic part or understand the steps. Usually, it happens to long documents where it\u2019s difficult to find necessary information, sections don\u2019t follow naturally from each other, cross-references are a mess, and so on. It makes the document virtually unusable.<\/p>\n

Tip<\/strong>: Firstly, think carefully about the overall layout of the document. Moreover, instead of a long topic, create several topics \u2014 there can be a landing topic and child topics like this:<\/p>\n

\n
\n
\n
\n
<\/div>\n

<\/div>\n<\/div>\n<\/div>

Source:\u00a0ClickHelp User Manual<\/a><\/figcaption><\/figure>\n

Also, create a table of content for your documentation like in books, so users will not have to read the whole document but only the necessary part.<\/p>\n

Too much Jargon<\/h1>\n

Unfortunately, some technical writers forget that they create documentation for people and they are different that\u2019s why some documents may contain jargon. It\u2019s inappropriate if you create documents for general audiences, the content should be easy-to-understand for every reader. Of course, internal and\/or specialized documentation is an exclusion but a tech writer should also follow the main rule \u2014 create concise and clear documentation.<\/p>\n

Tip<\/strong>: Identify and visualize your readers, the best idea is to gather a focus group to communicate with your readers directly. Consider what level and type of technicality in the writing will be appropriate for them and what won\u2019t be. If there are no possibilities to learn your target audience or you\u2019re not sure your readers will know all the technical terms you plan to use in your document, it\u2019s a good idea to include a glossary at the start of a text. Also, you can use the\u00a0readability metrics<\/a>\u00a0to make sure that your audience will easily understand your documentation.<\/p>\n

Poor Content<\/h1>\n

By \u2018poor content\u2019 I mean poor punctuation, typos, mistakes and the like. Of course, we\u2019re all people and can miss something but you should do your best to write high-quality content because mistakes are just inappropriate in documentation.<\/p>\n

Tip<\/strong>: Usually, reviewers check content for mistakes but if your team is small, in this case, use grammar checkers like\u00a0Grammarly<\/a>\u00a0or\u00a0Hemingway<\/a>\u00a0to make your documentation user-friendly. Additionally, you can also ask your team members to read your documentation.<\/p>\n<\/div>\n<\/div>\n<\/section>\n

\n
\n
\n
\n

What are your tips for creating high-quality documentation?<\/strong><\/p>\n<\/div>\n<\/div>\n<\/section>\n

\n
\n
\n
\n

Ann Green, Content Manager at\u00a0ClickHelp.com \u2014 best online documentation tool for SaaS vendors<\/strong><\/a><\/p>\n<\/div>\n<\/div>\n<\/section>\n

\n

\n

\n

\n

\n

SOURCE: https:\/\/medium.com\/@ann.green\/common-mistakes-in-technical-writing-68a3435f912e<\/a><\/div>\n
<\/div>\n
<\/div>\n
<\/div>\n
<\/div>\n
Written by<\/strong><\/div>\n
\n
\"Ann<\/a><\/div>\n
<\/div>\n
Ann Green<\/a><\/div>\n
\n
\n
Content Manager at ClickHelp. In my blog, I write about technical writing.<\/span><\/div>\n<\/div>\n<\/div>\n<\/div>\n
<\/div>\n
<\/div>\n
<\/div>\n
<\/div>\n","protected":false},"excerpt":{"rendered":"

Let\u2019s have a look at the most common mistakes in technical writing, so you\u2019ll avoid them. I\u2019ll also provide you […]<\/p>\n","protected":false},"author":2,"featured_media":2835,"comment_status":"closed","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,47,21,40],"tags":[],"class_list":["post-2833","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-bloghassler-ec","category-clickhelp","category-medium","category-productividad","category-technical-writer"],"_links":{"self":[{"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/posts\/2833","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=2833"}],"version-history":[{"count":1,"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/posts\/2833\/revisions"}],"predecessor-version":[{"id":2836,"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/posts\/2833\/revisions\/2836"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/media\/2835"}],"wp:attachment":[{"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/media?parent=2833"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/categories?post=2833"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.hassler.ec\/wp\/wp-json\/wp\/v2\/tags?post=2833"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}