Support/Goals/2011Q2/KB Doc Policies
Knowledge Base Policies for the new rapid release process
Documentation procedure
The schedule for Firefox 5 is slightly different than the subsequent (Fx 6, 7, 8, etc.) releases. Also, during the Firefox 5 development period we'll be starting the other Firefox "trains." Eventually we'll always have four different trains running — one each on the nightly, aurora, beta and release channels. This sets up a documentation schedule that looks like this:
- Draft: We'll have four weeks to draft new articles and updates to existing articles. At the beginning of this time we'll identify the priority articles based on:
- New features in the Aurora build.
- Fixes and/or changes to existing features in the Aurora build.
- Updates and new articles needed based on feedback from the current Release build.
- Finalize: Once the release moves to the Beta channel, we'll have two weeks to finalize our articles. During this time we'll:
- Add screenshots and screencasts if necessary
- Review and approve the articles
- Mark the articles as "ready for localization" (new feature - bug 639806)
- Localize: Once the articles are finalized, there will be four weeks to localize before release.
Note: The Localize stage coincides with the Draft stage of the next release. So when we are localizing Firefox 5 articles, for example, we'll also be drafting Firefox 6 articles.
Fx release and documentation schedule
The schedule for Firefox 5 is slightly different than the subsequent (Fx 6, 7, 8, etc.) releases. Also, during the Firefox 5 development period we'll be starting the other Firefox "trains." Eventually we'll always have four different trains running — one each on the nightly, aurora, beta and release channels. This sets up a documentation schedule that looks like this:
- Draft: We'll have four weeks to draft new articles and updates to existing articles. At the beginning of this time we'll identify the priority articles based on:
- New features in the Aurora build.
- Fixes and/or changes to existing features in the Aurora build.
- Updates and new articles needed based on feedback from the current Release build.
- Finalize: Once the release moves to the Beta channel, we'll have two weeks to finalize our articles. During this time we'll:
- Add screenshots and screencasts if necessary
- Review and approve the articles
- Mark the articles as "ready for localization" (new feature - bug 639806)
- Localize: Once the articles are finalized, there will be four weeks to localize before release.
Note: The Localize stage coincides with the Draft stage of the next release. So when we are localizing Firefox 5 articles, for example, we'll also be drafting Firefox 6 articles.
Article Tracking
For Firefox 4, I created a Google docs spreadsheet that I used to keep track of the update progress. I think that worked well and I'd like a better solution that allows others to view and modify the document.
We should track article updates with a table like this:
| Article | Status | Notes |
| How do I stop websites from tracking me? | Needs Update | Preference moved to Privacy panel in Fx5 |
| Channel Switcher | Needs Review | Documentation needed on the new channel switching feature |
| Updating Firefox | Complete | Needs an update for the new automatic update process in Fx 5 |
From now on we'll track articles on this page.
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} so that it still means "For 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.
Since fx35 is already a special case, we're going to try to coordinate to remove the remaining fx3 sections. Cheng will scan the DB to find the remaining ones. Soon-ish we'll drop fx3 so we don't have to special case it, as well.
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
Drop fx3 from showfor Bug 651220- We're going to special case fx3 like fx35 for now because there are too many (about 45) articles to update.
- Warning for non-supported Firefox versions Bug 651230
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.
Article Archive
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 100 to 200 articles.
Ready for Localization
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.
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:
- We want to prevent people from mistakenly posting questions to begin with. So we have a bug to lock or hide the discussion tab where we want (e.g. /ask) - https://bugzilla.mozilla.org/show_bug.cgi?id=648257
- There is a bug to add a message at the top of these forums with a prominent link to the AAQ form https://bugzilla.mozilla.org/show_bug.cgi?id=652537
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.