Support/Goals/2011Q2/KB Doc Policies

From MozillaWiki
Jump to: navigation, search

Developing Policies

With the new Firefox release schedule we need to clarify how work on the KB should proceed. How do we prioritize our work, what should get localized and when, how should approvals work, when do we archive an article, etc. are some of the questions that need to be answered. I've outlined the basic mechanics around documentation below. That will help inform the policies which I'll draft as a single document and then use that to update our KB contributor documentation where necessary.

To do:

Documentation procedure

With the new Firefox six week release schedule, we'll be moving our documentation schedule to a six week cycle also. The schedule for Firefox 5 is slightly different than the subsequent schedule for Firefox 6 and beyond so I'll describe the latter as it will eventually be the new routine.

Fx-generic-schedule.png

Weeks 1 - 4

Release = Fx 6, Beta = Fx 7, Aurora = Fx 8, Nightly = Fx 9

  • Localize Fx 7: Once the articles are finalized, there will be four weeks to localize before release. We'll have marked revisions as ready for localization so they'll show up on Localization dashboards. Also, Localizers can keep abreast of what changes are happening by following the Article Tracking page.
    • Note: In the two weeks previous to this we may have also made updates based on feedback from the Fx 6 release that will also be included in this batch of articles to localize.
  • Draft Fx 8: We'll have four weeks to draft new articles and updates to existing articles. We'll be working from the Article Tracking page which we'll have been updating since the previous documentation cycle.
  • Track Fx 9: This release will be on the Nightly channel. We'll follow the Release Tracking page to identify which changes and additions will need documentation. Articles that will need to be updated or proposals for new articles should be added to the Article Tracking page along with links to the appropriate feature page and general notes about what will need to be documented. The details of this should be discussed in the Article's forum thread also linked from this page. The tracking of Firefox 9 features is an ongoing process that will continue through it's Beta phase but after it moves to Aurora the main changes should only be the possible removal of a feature.
  • Archive: Since Firefox and our documentation will be changing as new versions are released, we'll use this time to evaluate whether there are any articles that are:
    • Obsolete because Firefox has changed
    • Obsolete because they get so few views as to not be of concern to the vast majority of Firefox users.

Weeks 5 & 6

Release = Fx 7, Beta = Fx 8, Aurora = Fx 9, Nightly = Fx 10

  • Update Fx 7: Firefox 7 will have been released so, if necessary, we'll be able to go back and make adjustments to our documentation based on feedback from the support forums and live chat.
  • Finalize Fx 8: Once the release moves to the Beta channel, we'll have two weeks to finalize these articles that were drafted. During this time we'll:
    • Add screenshots and screencasts if necessary
    • Review and approve the articles
    • Mark the final Fx8 revision as Ready for Localization
  • Begin Tracking Fx 10: This release will now be on the Nightly channel.

Article Tracking

The Article Tracking page will be the central place for keeping up with what work is happening on knowledge base articles.

The page lists:

  • Near-term schedule
  • Articles to be updated
    • Link to relevant feature page
    • Current status
    • Notes
    • Link to discussion thread

Changes to {for}

This rapid release cycle has some implications for how we use {for} in our articles. Also Firefox will move to a silent update model which will mean users (for the most part) are always running the current version of Firefox. Here are the changes to {for} behavior that will allow us to keep up:

  • Change the current meaning of {for fx4} to mean "For Firefox 4 and up."
  • Add a new modifier syntax, {for =fx5} to mean "For Firefox 5 only." (The current meaning of "{for fx4}".)
  • Special case {for fx35} and {for fx3} so that they still mean for Firefox 3 only or Firefox 3.5-3.6 only.

In the future, if it's necessary, we may introduce a "less than" syntax: {for <fx6} which would mean "For Firefox less than 6" or "Firefox 5 or less." (This would make {for fx6} and {for <fx6} logical opposites.) This has been deemed unnecessary at this time.

To better support Windows XP and Vista/7, add two new operating systems, 'winxp' and 'win7'. The current 'win' would continue to mean "any windows version" while the new operating systems are hopefully obvious. ('win7' would have to mean Windows Vista or 7.) This doesn't mean we have to immediately update all articles with with separate XP and Win7 instructions. Current articles won't break. We should come up with a list of priority articles that would benefit the most from separate instructions and work them into our regular updates.

Additionally but not immediately, we'll add a site-wide warning to old, no-longer supported versions of the browser (for example, when 6 comes out we will start displaying the warning to users on 4).

Related bugs:

  • Add 'winxp' and 'win7' to showfor Bug 651226
  • Change showfor semantics and add = operator Bug 651225
  • Warning for non-supported Firefox versions Bug 651230

Article Archive

New Feature - Bug 651851

As we release Firefox every six weeks the issues and items that users will need documentation for will change at a much faster rate. There will be a lot of articles (like troubleshooting crashes, or using bookmarks) that may never go away but there will others that become obsolete or not of concern for users. We should archive these article and focus on the most pressing issues. We should be able to document 99% of what users need in less than 200 articles (we currently have almost 400 English articles).

With this feature, we can move an article to the archive by clicking a checkbox on the admin interface. This will remove the article from all dashboards (including localization dashboards) and from the normal search. You can still see the article by using the advanced search, and of course links to the article would be preserved. However there will be a banner on top of the article making it clear that the article is no longer maintained and might be out of date.

Archiving an article is not a one-way street. Once an article is archived we will monitor the stats, to make sure that the article wasn't a popular one. In case we made a mistake it's as easy as clicking a checkbox to get the article back on the dashboards.

Ready for Localization

New Feature - Bug 639806

When an English article is being worked on actively, we don't have a good way to tell localizers when it's final and can be translated. Currently, every time it's edited and marked with the second or third revision levels, it shows up on their dashboards as needing to be updated. We need a way to mark and unmark an article as ready for localization so that we can reduce the noise on localization dashboards.

The Ready for Localization feature will let us mark specific revisions as ready to localize. So, for example, we can mark the current revision as ready for localization for Fx5 and then start drafting Fx6 changes. Those new revisions won't show up on the localization dashboard. Then in 6 weeks or so when they are done we can mark the final one as ready for localization and that one will show up on localization dashboards.

"Ready for localization" will be a checkbox on the article page. When that checkbox is unchecked, the article will be displayed in a special way on the localization dashboard (eg. grayed out), and the tooltip will tell, that the article is currently worked on. You can then learn more about it by going to the discussion page of the article, or just wait until the article is marked as "ready for localization" at which point the article will appear as needing an update on your dashboard.

Article discussions

We should start using the discussion tab on each article. The idea is, you subscribe to notifications so you know which article are being talked about (similar to today minus the main article forum list). I’d propose that we use the KB Article Forum to discuss issues, thoughts, policies for articles in general plus proposals for new articles.

The main issue with moving to this workflow is that the vast majority of posts in these forums to date are support requests. So we have a few things to do before this is really viable:

In addition we should post a message in misplaced support request threads like we normally do along with a link to https://support.mozilla.com/questions/new and then we should delete the thread. I don't think there is any problem with deleting the threads as the original poster seems to get the message and doesn't post again in that thread.

Screenshots and Screencasts

We should make sure that articles are written to work without images or videos. I think both images and videos are important and greatly increase the helpfulness of an article but they can’t be mandatory. Localizers should feel free to use or delete them as they see fit.

Also, given how helpful screenshots and screencasts are, we need good documentation on creating them for contributors.

Retrieved from "https://wiki.mozilla.org/index.php?title=Support/Goals/2011Q2/KB_Doc_Policies&oldid=319690"