The Mozilla Support Blog

Rocking the helpful web since 2007.
Categories: Contributor News

Writing concise documents

7 responses

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%!

7 comments on “Writing concise documents”

  1. Greg K Nicholson wrote on

    ‘ “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. ’

    It’s also nonsensical.

    The part after the last comma seems to be a separate clause, which needs a semi-colon, a dash or a sentence-break before it. And the first part doesn’t actually say anything.

    You probably want to say:

    “Importing settings, saved passwords, cookies, and history is an advanced operation that will replace existing Firefox data.”

  2. Chris Ilias wrote on

    Thanks Greg! That’s exactly what this post is about. Great feedback!

  3. Mossop wrote on

    Of course by removing the redundant information you are also reducing the keywords and terms for search engines like Google to use. This could drop the article lower in the search results for how to import data from Flock.

  4. Majken “Lucy” Connor wrote on

    I agree with the spirit of this post, if not with the example cited.

    We need to make sure articles are not only easy to read, but also easy to skim. Big chunks of text make it harder for the user to be confident they’re at the right place and some may give up rather than trying to catch the gist.

    However I think we do need to be careful not to go to the other extreme. Words and information might be redundant, but they might be necessary context to make a sentence make sense. There’s a real danger in assuming the user is correctly inferring from previous text.

    For example, there’s a reason this was in brackets – (saved passwords, cookies, and history) – because they’re examples of the types of data. In the suggested change they become a proper list, which actually has an entirely different meaning.

    I think a better way to shorten this information would be to drop the excess off the end:

    “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 existing data.”

  5. Bo wrote on

    This was my example, and I knew it was redundant – I was trying to make it really scary on purpose. Greg’s grammatical comments are well taken, though.

  6. George wrote on

    Your contribution on the issue of concise writing is very helpful.

    I need some help. I have a lot of online research resources for a book project. Some of the material is saved on a word processor and the rest online on Favorites and Bookmarks. I want to digitally organize the material to facilitate the drafting of the book. What do I do? I am looking at Deli.cio.us, a Social Bookmarking application regarding this. Is it ok or there is a better way?

  7. Peter wrote on

    The Illuimine website has a whole host of article around writing clearly and concisely, in my oppinion one of the best is this one linked below titled No Bull Less Fog.
    http://www.illumine.co.uk/blog/2008/11/no-bull-less-fog/