What should we document?

Verdi

Planet Mozilla viewers – you can watch this video on YouTube.

This is a followup to my post on figuring out what’s new in Firefox and is part of our technical writing program for SUMO.

Once we’ve figured out what changes will be visible to users, we have to figure out what articles need to be written or updated. Here’s how I figure that out:

  • First I determine what changes need to be documented. Not every change needs to be documented (or at least, documented on SUMO).
    • Here are some things we generally DON’T document:
      • Developer tools
      • Changes to our support for web standards (like unprefixing a new CSS element).
      • Minor visual changes. In the past we’ve made the outline of buttons more or less prominent for example without updating our documentation.
      • “Under the hood” changes like speed improvements and new javascript engines.
    • Here are things we DO document:
      • New features like Facebook Messenger or Firefox Reset.
      • Changes to existing features. Our site supports showing different sets of instructions to different operating systems and different versions of Firefox. In this way we can customize the article to match what people are using. Look at the Startup, home page and download settings article and switch the controls at the top from Firefox 18 to Firefox 17 and you will see that there is a section about add-on for Firefox 17 that isn’t there for Firefox 18.
      • Problems or questions we anticipate people will have. For example, Click to play blocklisting or ending support for Firefox 3.6.
  • Next I look at each change that needs to be documented and decide if it needs a new article or just an update to an existing article. Generally, if we already have an article on a topic, we probably just need to update it. New features or new problems generally require new articles. Occasionally it’s a little more complicated and we’ll have to discuss the best course of action.

If you have suggestions for making this particular workshop better, please reply to this thread in our knowledge base forum.