{"id":552,"date":"2009-04-09T09:46:13","date_gmt":"2009-04-09T16:46:13","guid":{"rendered":"http:\/\/blog.mozilla.org\/sumo\/?p=552"},"modified":"2009-04-09T09:46:13","modified_gmt":"2009-04-09T16:46:13","slug":"writing-concise-documents","status":"publish","type":"post","link":"https:\/\/blog.mozilla.org\/sumo\/2009\/04\/09\/writing-concise-documents\/","title":{"rendered":"Writing concise documents"},"content":{"rendered":"<p>Last month, website usability expert Neil Lee from the webdev team made a <a href=\"https:\/\/wiki.mozilla.org\/Support\/UX\/Audit\">usability audit of the Firefox Support website<\/a>. One observation he made was that some articles in our Knowledge Base are a bit verbose, making them harder than necessary to read. We&#8217;ve updated our <a href=\"http:\/\/support.mozilla.com\/kb\/Best+Practices+for+Support+Documents\">Best Practices for Support Documents<\/a> page, to include emphasis on writing concisely and reducing redundancy.<\/p>\n<p>For example, our <a href=\"http:\/\/support.mozilla.com\/kb\/Pop-up+blocker\">Pop-up Blocker article<\/a> contains much more information than is needed. It tries to explain the difference between pop-ups and pop-unders, devotes an entire paragraph to telling you that Firefox has a pop-up blocker that is on by default, and includes notes about the pop-up blocker not being full-proof, even though there is a large section on pop-ups not being blocked at the bottom. As a result, the user can get lost in the details and miss the overall message.<\/p>\n<p>Even short paragraphs and sections can be simplified. Here&#8217;s a recent example from an article about importing from Flock:<\/p>\n<p>&#8220;It is possible to import settings and other user data (saved passwords, cookies, and history) from Flock into Firefox. This is an advanced operation, however, and it will <strong>replace<\/strong> Firefox&#8217;s data and settings with the settings from Flock. Only attempt the following instructions if you are comfortable with deleting your Firefox settings and data:&#8221;<\/p>\n<ul>\n<li>The user doesn&#8217;t need to be reminded that the instructions are for importing from Flock to Firefox &#8212; that&#8217;s what the article is about.<\/li>\n<li>The fact that it is <em>Firefox<\/em> data that is being replaced with Flock data is assumed.<\/li>\n<li>The last sentence is redundant with the previous statements.<\/li>\n<\/ul>\n<p>That paragraph can be condensed to:<\/p>\n<p>&#8220;To import settings and other user data (saved passwords, cookies, and history), this is an advanced operation and will replace existing Firefox data.&#8221;<\/p>\n<p>It&#8217;s the same message, but clearer and more succinct.<\/p>\n<p>We are continuously monitoring how well we are meeting our <a href=\"http:\/\/blog.mozilla.org\/sumo\/2008\/09\/10\/the-vision-for-sumo-4\/\">Firefox users&#8217; expectations of their support experience<\/a>. The Knowledge Base user satisfaction score is already pretty good at 87% &#8212; let&#8217;s see if we can push it above 90%!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Last month, website usability expert Neil Lee from the webdev team made a usability audit of the Firefox Support website. One observation he made was that some articles in our &hellip; <a class=\"go\" href=\"https:\/\/blog.mozilla.org\/sumo\/2009\/04\/09\/writing-concise-documents\/\">Read more<\/a><\/p>\n","protected":false},"author":179,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[117],"tags":[],"_links":{"self":[{"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/posts\/552"}],"collection":[{"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/users\/179"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/comments?post=552"}],"version-history":[{"count":0,"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/posts\/552\/revisions"}],"wp:attachment":[{"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/media?parent=552"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/categories?post=552"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.mozilla.org\/sumo\/wp-json\/wp\/v2\/tags?post=552"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}