There have been lots of questions about how we should do things around editing the knowledge base — especially with the changes to the Firefox release cycle. I've drafted some policies that describe how we've been doing things, how we probably should being doing other things and how new features were intended to work.
Please look these over — KB Doc Policies — and add any comments or suggestions you have here.
I wrote these all in one document so they're easy to talk about. The idea is to update all of the KB documentation with these items.
There have been lots of questions about how we should do things around editing the knowledge base — especially with the changes to the Firefox release cycle. I've drafted some policies that describe how we've been doing things, how we probably should being doing other things and how new features were intended to work.
Please look these over — [https://wiki.mozilla.org/Support/KB_Doc_Policies KB Doc Policies] — and add any comments or suggestions you have here.
I wrote these all in one document so they're easy to talk about. The idea is to update all of the KB documentation with these items.
*[[Improve the Knowledge Base]]
*[[How the Knowledge Base works]]
*[[How to write Knowledge Base articles]]
*[[How to use For]]
Article Discussion: Needs to lock all the threads with [In KB] in the title for the KB articles forum.
Article Updates:
Updating an article:
Go to the Article Tracking, click the rank sort button.: Who is going to maintain ranks as they change every week?
Does the [Needs Review] thread naming process disappear?
What do "we" do with contributors that don't follow the rules (no thread, no [Needs Update] in the thread title, thread with no real request, Article Tracking not updated with the status or the new thread)? Are "we" the KB reviewers?
Article Tracking can be edited by anybody who has a Wiki account, who is going to maintain it and prevent spams? The same "we"?
Review:
"If the reviewer doesn't approve the article they should reject it and post their reasons and feedback in the thread.": I disagree. If the revision add some value, the editor or another person must edit the article based on the previous revision without rejecting it, so that it gives credits to the editor and we've got a real history by changelogs. For instance: June 15 Approved editor2 fixed typo, added fx5 screenshots June 10 Unreviewed editor1 added troubleshooting section
'"Approved revisions based on unreviewed or rejected revisions should give everyone credit.": It is similar to the previous item. Approvers must reject revisions that don't add some value.
Ready for localization: Your description talks about the steady state, but not the transition state. What will be the default flag for articles soon after its release today? If the default flag is false, nothing will appear in localization dashboards, if it is true, localization dashboards will show up the same articles as now. In the Article Tracking, there are only 7 articles ready for localization for Firefox 5, who is going to flag the others for Firefox 4+? When?
Archive Needs to be discussed in the Article Discussion forum and updated in the Article Tracking.
Writing articles:
Screenshots and screencasts: Aero style? How to do localized screenshots for mobile (no localized win32 version)?
Templates: needed for duplicated long content used in few articles or duplicated short content used in many articles.
no reference to bugs, to specific add-ons (only for some case: status4ever, shortcuts)
Here are my first comments:
*Article Discussion: Needs to lock all the threads with [In KB] in the title for the [/forums/knowledge-base-articles KB articles forum].
*Article Updates:
** ''Updating an article'':
***''Go to the Article Tracking, click the rank sort button.'': Who is going to maintain ranks as they change every week?
*** Does the [Needs Review] thread naming process disappear?
*** What do "we" do with contributors that don't follow the rules (no thread, no [Needs Update] in the thread title, thread with no real request, [https://wiki.mozilla.org/Support/Article_Tracking Article Tracking] not updated with the status or the new thread)? Are "we" the [[Meet the team#w_kb-reviewers|KB reviewers]]?
*** [https://wiki.mozilla.org/Support/Article_Tracking Article Tracking] can be edited by anybody who has a Wiki account, who is going to maintain it and prevent spams? The same "we"?
**''Review:''
*** ''"If the reviewer doesn't approve the article they should reject it and post their reasons and feedback in the thread."'':<br>I disagree. If the revision add some value, the editor or another person must edit the article based on the previous revision without rejecting it, so that it gives credits to the editor and we've got a real history by changelogs. For instance:<br>June 15 ''Approved'' editor2 ''fixed typo, added fx5 screenshots''<br>June 10 ''Unreviewed'' editor1 ''added troubleshooting section''
*** '''"Approved revisions based on unreviewed or rejected revisions should give everyone credit."'':<br>It is similar to the previous item. Approvers must reject revisions that don't add some value.
** ''Ready for localization'':<br>Your description talks about the steady state, but not the transition state. What will be the default flag for articles soon after its release [https://mail.mozilla.com/home/jsocol@mozilla.com/SUMO%20Schedule.html today]? If the default flag is false, nothing will appear in localization dashboards, if it is true, localization dashboards will show up the same articles as now. In the [https://wiki.mozilla.org/Support/Article_Tracking Article Tracking], there are only 7 articles ready for localization for Firefox 5, who is going to flag the others for Firefox 4+? When?
* Scope of the KB:
** ''New articles:'' add a reference to the [/forums/knowledge-base-articles KB articles forum].
**''Archive'' Needs to be discussed in the Article Discussion forum and updated in the [https://wiki.mozilla.org/Support/Article_Tracking Article Tracking].
* Writing articles:
**''Screenshots and screencasts'': Aero style? How to do localized screenshots for mobile (no localized win32 version)?
**''Templates:'' needed for duplicated long content used in few articles or duplicated short content used in many articles.
**no reference to bugs, to specific add-ons (only for some case: status4ever, shortcuts)
Article Discussion: Needs to lock all the threads with [In KB] in the title for the KB articles forum.
Yes, and all the other [Needs Review], etc. We'll also also have to put links back to these threads in the articles' discussion tabs.
Article Updates:
Updating an article:
Go to the Article Tracking, click the rank sort button.: Who is going to maintain ranks as they change every week?
I will although I don't think it needs to be done every week. I'm working on an update to the Article Tracking page right now that will list all of the articles (I've added their current rank), templates and proposals.
Does the [Needs Review] thread naming process disappear?
No. I just forgot that part. And now that I'm thinking about it I'm not sure about the permission needed to change thread titles. Will have to figure that out.
What do "we" do with contributors that don't follow the rules (no thread, no [Needs Update] in the thread title, thread with no real request, Article Tracking not updated with the status or the new thread)? Are "we" the KB reviewers?
Those are the people I'll try to contact and see if they're interested in joining us. And "us" means KB reviewers and anyone else who would like to contribute (they don't have to be editors). I'm sorry your name wasn't listed there Scoobi - fixing that now.
Article Tracking can be edited by anybody who has a Wiki account, who is going to maintain it and prevent spams? The same "we"?
Yes and always in these cases you can assume that ultimately I'm responsible but of course I appreciate it when others (like you often do) take it on.
Review:
"If the reviewer doesn't approve the article they should reject it and post their reasons and feedback in the thread.": I disagree. If the revision add some value, the editor or another person must edit the article based on the previous revision without rejecting it, so that it gives credits to the editor and we've got a real history by changelogs. For instance: June 15 Approved editor2 fixed typo, added fx5 screenshots June 10 Unreviewed editor1 added troubleshooting section
'"Approved revisions based on unreviewed or rejected revisions should give everyone credit.": It is similar to the previous item. Approvers must reject revisions that don't add some value.
I commented on this in the bug but I'm not married to doing it my way.
Ready for localization: Your description talks about the steady state, but not the transition state. What will be the default flag for articles soon after its release today? If the default flag is false, nothing will appear in localization dashboards, if it is true, localization dashboards will show up the same articles as now. In the Article Tracking, there are only 7 articles ready for localization for Firefox 5, who is going to flag the others for Firefox 4+? When?
For articles that are not part of updates for a release, we just leave them unmarked until we agree on a final revision. So for all of those Fx4+ articles that are done, we should go though and double-check they're good to go and then mark them ready for localization. Old articles that haven't changed in a while will just stay they way they are until we working on them again some time in the future.
Archive Needs to be discussed in the Article Discussion forum and updated in the Article Tracking.
I agree.
Writing articles:
Screenshots and screencasts: Aero style? How to do localized screenshots for mobile (no localized win32 version)?
Yes Areo style. Yes, mobile screenshots are a nightmare and there is no good solution yet.
Templates: needed for duplicated long content used in few articles or duplicated short content used in many articles.
I agree.
no reference to bugs, to specific add-ons (only for some case: status4ever, shortcuts)
I agree on the reference to bugs (although I did it in a mobile article once). We do write about plugins and some add-ons. I think these should just be decided on a case-by-case basis.
Holy cow! Thanks for all the feedback Scoobidiver. Let me try to answer...
''scoobidiver [[#post-40229|said]]''
<blockquote>
Here are my first comments:
*Article Discussion: Needs to lock all the threads with [In KB] in the title for the [/forums/knowledge-base-articles KB articles forum].
</blockquote>
Yes, and all the other [Needs Review], etc. We'll also also have to put links back to these threads in the articles' discussion tabs.
<blockquote>
*Article Updates:
** ''Updating an article'':
***''Go to the Article Tracking, click the rank sort button.'': Who is going to maintain ranks as they change every week?
</blockquote>
I will although I don't think it needs to be done every week. I'm working on an update to the Article Tracking page right now that will list all of the articles (I've added their current rank), templates and proposals.
<blockquote>
*** Does the [Needs Review] thread naming process disappear?
</blockquote>
No. I just forgot that part. And now that I'm thinking about it I'm not sure about the permission needed to change thread titles. Will have to figure that out.
<blockquote>
*** What do "we" do with contributors that don't follow the rules (no thread, no [Needs Update] in the thread title, thread with no real request, [https://wiki.mozilla.org/Support/Article_Tracking Article Tracking] not updated with the status or the new thread)? Are "we" the [[Meet the team#w_kb-reviewers|KB reviewers]]?
</blockquote>
Those are the people I'll try to contact and see if they're interested in joining us. And "us" means KB reviewers and anyone else who would like to contribute (they don't have to be editors). I'm sorry your name wasn't listed there Scoobi - fixing that now.
<blockquote>
*** [https://wiki.mozilla.org/Support/Article_Tracking Article Tracking] can be edited by anybody who has a Wiki account, who is going to maintain it and prevent spams? The same "we"?
</blockquote>
Yes and always in these cases you can assume that ultimately I'm responsible but of course I appreciate it when others (like you often do) take it on.
<blockquote>
**''Review:''
*** ''"If the reviewer doesn't approve the article they should reject it and post their reasons and feedback in the thread."'':<br>I disagree. If the revision add some value, the editor or another person must edit the article based on the previous revision without rejecting it, so that it gives credits to the editor and we've got a real history by changelogs. For instance:<br>June 15 ''Approved'' editor2 ''fixed typo, added fx5 screenshots''<br>June 10 ''Unreviewed'' editor1 ''added troubleshooting section''
*** '''"Approved revisions based on unreviewed or rejected revisions should give everyone credit."'':<br>It is similar to the previous item. Approvers must reject revisions that don't add some value.
</blockquote>
I commented on this in the [https://bugzilla.mozilla.org/show_bug.cgi?id=628634#c9 bug] but I'm not married to doing it my way.
<blockquote>
** ''Ready for localization'':<br>Your description talks about the steady state, but not the transition state. What will be the default flag for articles soon after its release [https://mail.mozilla.com/home/jsocol@mozilla.com/SUMO%20Schedule.html today]? If the default flag is false, nothing will appear in localization dashboards, if it is true, localization dashboards will show up the same articles as now. In the [https://wiki.mozilla.org/Support/Article_Tracking Article Tracking], there are only 7 articles ready for localization for Firefox 5, who is going to flag the others for Firefox 4+? When?
</blockquote>
For articles that are not part of updates for a release, we just leave them unmarked until we agree on a final revision. So for all of those Fx4+ articles that are done, we should go though and double-check they're good to go and then mark them ready for localization. Old articles that haven't changed in a while will just stay they way they are until we working on them again some time in the future.
<blockquote>
* Scope of the KB:
** ''New articles:'' add a reference to the [/forums/knowledge-base-articles KB articles forum].
**''Archive'' Needs to be discussed in the Article Discussion forum and updated in the [https://wiki.mozilla.org/Support/Article_Tracking Article Tracking].
</blockquote>
I agree.
<blockquote>
* Writing articles:
**''Screenshots and screencasts'': Aero style? How to do localized screenshots for mobile (no localized win32 version)?
</blockquote>
Yes Areo style. Yes, mobile screenshots are a nightmare and there is no good solution yet.
<blockquote>
**''Templates:'' needed for duplicated long content used in few articles or duplicated short content used in many articles.
</blockquote>
I agree.
<blockquote>
**no reference to bugs, to specific add-ons (only for some case: status4ever, shortcuts)
</blockquote>
I agree on the reference to bugs (although I did it in a mobile article once). We do write about plugins and some add-ons. I think these should just be decided on a case-by-case basis.
I intend to make a blog post (and probably a video) about the Article Tracking page but I just wanted to note that I just updated it with a list of all the English articles, templates, and start page pieces.
One thing I'm undecided about is when an article needs to be updated for a fx release, do we copy it to that table or remove it from the all articles table and put it in the release table? I'm kind of leaning to copying because it's possible to be in two release tables.
Also I noticed that scoobidiver (?) made a "archived" status template. I think that's a good idea and I'm also thinking that we should only leave archived articles on the list for a short time. Maybe 2 weeks?
I intend to make a blog post (and probably a video) about the [https://wiki.mozilla.org/Support/Article_Tracking Article Tracking] page but I just wanted to note that I just updated it with a list of all the English articles, templates, and start page pieces.
One thing I'm undecided about is when an article needs to be updated for a fx release, do we copy it to that table or remove it from the all articles table and put it in the release table? I'm kind of leaning to copying because it's possible to be in two release tables.
Also I noticed that scoobidiver (?) made a "archived" status template. I think that's a good idea and I'm also thinking that we should only leave archived articles on the list for a short time. Maybe 2 weeks?
I'm kind of leaning to copying because it's possible to be in two release tables.
Me too.
Also I noticed that scoobidiver (?) made a "archived" status template. I think that's a good idea and I'm also thinking that we should only leave archived articles on the list for a short time. Maybe 2 weeks?
''Verdi [[#post-40288|said]]''
<blockquote>
I'm kind of leaning to copying because it's possible to be in two release tables.
</blockquote>
Me too.
<blockquote>
Also I noticed that scoobidiver (?) made a "archived" status template. I think that's a good idea and I'm also thinking that we should only leave archived articles on the list for a short time. Maybe 2 weeks?
</blockquote>
Yes, I did it for [[How do I switch update channels?]]. OK for the 2-week delay before the removal.
I just wanted to follow up and let you know that I updated the KB contributor documentation with all of this new info:
*[[Improve the Knowledge Base]]
*[[How the Knowledge Base works]]
*[[How to use For]]
*[[How to use Templates]]
Must be written somewhere, but have yet to find it: the licencing of original en articles as well as translations, in the sense "by signing up the localizer agrees to provide his/her translations under the conditions of xyz license ", clearing this way the legal side of the copyright question, the question of the right to retract (and publish too,,,) the work once done etc.
Regards
smo
Must be written somewhere, but have yet to find it: the licencing of original en articles as well as translations, in the sense "by signing up the localizer agrees to provide his/her translations under the conditions of xyz license ", clearing this way the legal side of the copyright question, the question of the right to retract (and publish too,,,) the work once done etc.
Regards
smo
I don't know if this covers it but, at the bottom of every support.mozilla.com webpage, including this one, you will see:
<blockquote>
[http://mozilla.com/privacy-policy.html Privacy Policy] | [http://mozilla.com/about/legal.html Legal Notices] | [http://mozilla.com/legal/fraud-report/index.html Report Trademark Abuse]
<br>
<br> Except where otherwise [http://mozilla.com/about/legal.html#site noted],
content on this site is licensed under the <br>
[http://creativecommons.org/licenses/by-sa/3.0/
Creative Commons Attribution Share-Alike License v3.0] or
any later version. </blockquote>
A "How to use Keywords" article is required as many people add keywords duplicated with the title or between each other because of the stemming algorithm (e.g, block, blocking), which bias search results. See this thread on how keywords work and this thread about keyword rules.
A "How to use Keywords" article is required as many people add keywords duplicated with the title or between each other because of the stemming algorithm (e.g, block, blocking), which bias search results. See [/forums/contributors/704882 this thread on how keywords work] and [/forums/knowledge-base-articles/704900 this thread about keyword rules].
An [[Adding screenshots]] update would be also good. See [/en-US/kb/How%20to%20clear%20Search%20bar%20history/discuss/1559 this thread].
I'm pretty sure we don't use that terms of service article.
I'm pretty darn sure the creative commons license that Alice notes is what applies. It should be mentioned somewhere besides the footer.
A keywords section should be added and Screenshots definitely needs a new article.
I'm pretty sure we don't use that terms of service article.
I'm pretty darn sure the creative commons license that Alice notes is what applies. It should be mentioned somewhere besides the footer.
A keywords section should be added and Screenshots definitely needs a new article.
I'm pretty darn sure the creative commons license that Alice notes is what applies. It should be mentioned somewhere besides the footer.
I agree for both. The problem is that it isn't translated in any languages. That's not a SUMO issue but rather a Mozilla's website issue.
A keywords section should be added and Screenshots definitely needs a new article.
I also agree.
''Verdi [[#post-40580|said]]''
<blockquote>
I'm pretty sure we don't use that terms of service article.
</blockquote>
See the link in [[Forum and chat rules and guidelines]]. But it's easy to replace.
<blockquote>
I'm pretty darn sure the creative commons license that Alice notes is what applies. It should be mentioned somewhere besides the footer.
</blockquote>
I agree for both. The problem is that it isn't translated in any languages. That's not a SUMO issue but rather a Mozilla's website issue.
<blockquote>
A keywords section should be added and Screenshots definitely needs a new article.
</blockquote>
I also agree.
''scoobidiver [[#post-40584|said]]''
<blockquote>
The problem is that it isn't translated in any languages. That's not a SUMO issue but rather a Mozilla's website issue.
</blockquote>
I filed [https://bugzilla.mozilla.org/show_bug.cgi?id=669605 bug 669605 - Mozilla Privacy Policy], [https://bugzilla.mozilla.org/show_bug.cgi?id=669606 bug 669606 - Legal Notices], [https://bugzilla.mozilla.org/show_bug.cgi?id=669607 bug 669607 - Violating Website Report], and [https://bugzilla.mozilla.org/show_bug.cgi?id=669608 bug 669608 - Creative Commons Attribution Share-Alike v3.0] for the pages that link to from Mozilla's website footer.
''Verdi [[#post-40580|said]]''
<blockquote>
I'm pretty sure we don't use that terms of service article.
</blockquote>
https://support.mozilla.com/en-US/chat?new_chat also.
''scoobidiver [[#post-40571|said]]''
<blockquote>
An [[Adding screenshots]] update would be also good. See [/en-US/kb/How%20to%20clear%20Search%20bar%20history/discuss/1559 this thread].
</blockquote>
There's a revision to [[Adding screenshots]] that's pending review, based on the discussion here: [/forums/contributors/707035?last=40736]
This one isn't linked from any other articles. It'd be archived.
''AliceWyman [[#post-40740|said]]''
<blockquote>
Oh, and [[About Firefox Support]] also links to [[Terms of Service]].
</blockquote>
This one isn't linked from any other articles. It'd be archived.
... raising bashfully my hand: behind my comment about legal issues was a concern about the following scenarios:
the author of the translation decides to pull back his/her work and demands SuMo to cease and desist
some person, different from the author (?) , demands the texts to be pulled back
the author insists on his/her version that was changed in the review process
the author requests to eliminate/remove texts done/redone by others
(keep on, think dirty)
This all is probably far-fetched, but my reason for writing it up was reality-diven (ask Kadir about it).
Hope anyhow we are well-prepared for this kind of nasty situations.
regards
smo
... raising bashfully my hand: behind my comment about legal issues was a concern about the following scenarios:
* the author of the translation decides to pull back his/her work and demands SuMo to cease and desist
* some person, different from the author (?) , demands the texts to be pulled back
* the author insists on his/her version that was changed in the review process
*the author requests to eliminate/remove texts done/redone by others
* (keep on, think dirty)
This all is probably far-fetched, but my reason for writing it up was reality-diven (ask Kadir about it).
Hope anyhow we are well-prepared for this kind of nasty situations.
regards
smo
