View source for Support/Goals/2011Q2/KB Doc Policies

{{draft}}
=Knowledge Base Policies for the new rapid release process=
==Fx release and documentation schedule==
[[File:Fxdocschedule.png]]

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" '''([https://bugzilla.mozilla.org/show_bug.cgi?id=639806 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.

'''We should track article updates with a table like this on [[Support/Article_Tracking|this page]]:'''
{| border="1" style="border: 2px solid rgb(0, 0, 0); border-collapse: collapse; width: 700px;"
|-
|style="font-weight: bold; background: #DDD;" | Article 
|style="font-weight: bold; background: #DDD;" | Status 
|style="font-weight: bold; background: #DDD;" | Notes 
|-
| [https://support.mozilla.com/en-US/kb/how-do-i-stop-websites-tracking-me How do I stop websites from tracking me?] 
| {{StatusAtRisk|status=Needs Update}} 
| [https://bugzilla.mozilla.org/show_bug.cgi?id=645063 Preference moved to Privacy panel] in Fx5 
|-
| Channel Switcher
| {{StatusBlocked|status=Needs Review}} 
| Documentation needed on the new [https://wiki.mozilla.org/ChannelSwitching/ChannelSwitchingFeature channel switching feature] 
|-
| [https://support.mozilla.com/en-US/kb/Updating+Firefox Updating Firefox]
| {{StatusHealthy|status=Complete}} 
| Needs an update for the new automatic update process in Fx 5 
|}

==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 [https://bugzilla.mozilla.org/show_bug.cgi?id=651226 Bug 651226]
*Change showfor semantics and add = operator [https://bugzilla.mozilla.org/show_bug.cgi?id=651225 Bug 651225]
*<strike>Drop fx3 from showfor [https://bugzilla.mozilla.org/show_bug.cgi?id=651220 Bug 651220]</strike>
**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 [https://bugzilla.mozilla.org/show_bug.cgi?id=651230 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==
[https://bugzilla.mozilla.org/show_bug.cgi?id=651851 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 100 to 200 articles.

==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.