Writing concise documents

Chris Ilias


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 Knowledge Base are a bit verbose, making them harder than necessary to read. We’ve updated our Best Practices for Support Documents page, to include emphasis on writing concisely and reducing redundancy.

For example, our Pop-up Blocker article 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.

Even short paragraphs and sections can be simplified. Here’s a recent example from an article about importing from Flock:

“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 replace Firefox’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:”

  • The user doesn’t need to be reminded that the instructions are for importing from Flock to Firefox — that’s what the article is about.
  • The fact that it is Firefox data that is being replaced with Flock data is assumed.
  • The last sentence is redundant with the previous statements.

That paragraph can be condensed to:

“To import settings and other user data (saved passwords, cookies, and history), this is an advanced operation and will replace existing Firefox data.”

It’s the same message, but clearer and more succinct.

We are continuously monitoring how well we are meeting our Firefox users’ expectations of their support experience. The Knowledge Base user satisfaction score is already pretty good at 87% — let’s see if we can push it above 90%!