In questo articolo vengono spiegati alcuni aspetti del funzionamento della Knowledge Base.

La Knowledge Base è un wiki con i super-poteri

Essi sono:

• Sintassi wiki specifica: sebbene venga utilizzata la sintassi MediaWiki (come quella di Wikipedia) nella maggior parte dei casi, il nostro wiki è progettato specificamente per il supporto a Mozilla e comprende anche una speciale istruzione (chiamata {for}) con la quale è possibile mostrare ad esempio un insieme di informazioni agli utenti Windows ma non agli utenti Mac.
• Sistema di revisione: poiché vogliamo sempre essere sicuri che gli utenti ricevano informazioni corrette e aggiornate, le modifiche ai nostri articoli devono essere revisionate e approvate prima che vadano online.
• Traduzioni: la maggior parte dei nostri utenti parla una lingua diversa dall'inglese, e perciò abbiamo un sistema per consentire la traduzione degli articoli dall'inglese in altre lingue.

Utenti e perimetro della Knowledge Base

Con oltre 400 milioni di utenti di Firefox, la Knowledge Base deve essere scritta per un pubblico generale più che per chi ha già familiarità con la terminologia tecnica relativa ai computer. Principalmente vengono trattate le caratteristiche dei programmi (come le schede, i segnalibri e Sync) e la risoluzione dei problemi (come i crash o difficoltà nel caricare le pagine web). Non viene trattato ogni aspetto, configurazione o problema, ma ci basiamo invece sul riscontro degli utenti (nelle discussioni relative agli articoli, nei forum di supporto e nel numero di visualizzazioni) e utilizziamo la nostra esperienza e giudizio per decidere esattamente di che cosa occuparci.

Quali sono gli argomenti di cui NON ci occupiamo nella Knowledge Base?

• Trucchi o modifiche avanzate dei prodotti
• Caratteristiche avanzate o destinate agli sviluppatori come la console degli errori o la console web

Organizzazione del lavoro

Come si stabiliscono le priorità?

Ci concentriamo sugli articoli a seconda della loro popolarità. Ciò generalmente rappresenta la priorità dei nostri utenti. Attualmente i 20 articoli più visitati assorbono più della metà delle visualizzazioni. Migliorando i nostri articoli più visitati può potenzialmente aiutare lo stesso numero di persone che possono beneficiare del miglioramento degli ultimi 100. Teniamo traccia delle modifiche da effettuare in questo pannello, ordinato secondo le priorità in modo da poter capire subito su quali articoli occorre lavorare prima.

Eccezioni:
Ovviamente la popolarità non è l'unica discriminante. Vengono tenute in conto anche queste eccezioni:

• Problemi critici: occasionalmente, nuovi problemi riportati nel nostro forum di supporto vengono gestiti meglio aggiornando tempestivamente un articolo. Per esempio, un problema che colpisce gli utenti del plugin Flash (il 99% degli utenti di Firefox) viene ad avere prorità maggiore rispetto a una modifica di poco conto destinata a comparire in una prossima versione di Firefox.
• Richieste anticipate occasionalmente aggiorniamo un articolo in previsione dell'introduzione di una nuova caratteristica o della modifica di una esistente. L'articolo in questione potrebbe non avere una priorità alta, ma siamo sufficientemente sicuri che diverrà popolare basandoci sull'esperienza e sulle previsioni di marketing.
• Documentazione per piattaforma mobile: i prodotti Firefox per Android e Firefox OS hanno relativamente pochi utenti e gli articoli che li riguardano non possono "competer" in popolarità con quelli relativi a Firefox. Quindi numeri vanno comunque contestualizzati alla richiesta di informazioni e documentazione dello specifico prodotto.
• Link interni: articoli richiamati da altri prodotti o pagine presenti sul sito mozilla.org.

Localizzazione:
Al fine di minimizzare il lavoro per i localizzatori, cerchiamo di concentrare in un periodo di sei settimane le modifiche ai 20 articoli più consultati. Gli aggiornamenti non essenziali per questi articoli (nuove caratteristiche, piccoli aggiustamenti e miglioramenti) vengono fatti per la versione inglese ma non immediatamente marcati come pronti per la localizzazione. Quattro settimane prima del rilascio di una nuova versione, gli aggiornamenti per i 20 articoli più consultati vengono marcati come pronti per la localizzazione. Si cerca quindi di mantenere questi articoli stabili per le successive sei settimane. Talvolta, problemi improvvisi o errori possono richiedere ulteriori modifiche. Ogni sei settimane viene creato un elenco delle priorità (come ad esempio questo), basato sulla nostra esperienza relativamente alla sezione in inglese della Knowlesge Base, da utilizzare come falsariga dai localizzatori.

Dove si discute degli articoli?

Generalmente le discussioni sono di due tipi:

• Singoli articoli: ciascun articolo presenta una scheda relativa alle discussioni. Gli utenti registrati possono inserire commenti e suggerimenti per l'articolo e in questo spazio è possibile discutere su ciò che è possibile fare per migliorarlo.
  
• Intera Knowledge Base: le nuove idee e le strategie relative a tutta la KB possono essere discusse nel forum degli articoli.

Come mantenere gli articoli coerenti con le ultime versioni dei prodotti Mozilla?

Ci sono quattro versioni per ciascun prodotto Mozilla (ossia Firefox, Firefox per piattaforma Mobile, Firefox OS). Ci si riferisce ad esse come "treni." Ciascun treno si muove da un canale (o binario, per continuare ad usare la metafora del treno) all'altro ogni sei settimane. I canali sono Nightly, Aurora, Beta e Release. Per sei settimane, mentre si trovano nel canale Nightly, ai prodotti vengono aggiunte nuove caratteristiche e funzionalità. Successivamente, quella versione passa nel canale Aurora per essere sottoposto a verifiche. Dopo sei settimane su Aurora, si sposta sul canale Beta. E finalmente, dopo sei settimane di test sul canale Beta, quella versione diventa il rilascio stabile per il prodotto. Al fine di rimanere aggiornati relativamente alle modifiche di prodotto, anche la scrittura della documentazione segue un ciclo di sei settimane.

Ciclo della documentazione: settimane 1 - 4

• Localizzazione di Beta: una volta che gli articoli sono stati finalizzati (nel ciclo precedente) ci saranno a disposizione quattro settimane per la localizzazione prima del rilascio. Essi saranno marcati come pronti per la localizzazione in modo da comparire nel pannello di localizzazione dei vari gruppi di lavoro.
  • Nota: nelle due settimane precedenti potremmo aver effettuato anche altre modifiche basandoci sui suggerimenti del rilascio precedente. In questo caso ci saranno altri articoli da localizzare in questa stessa tornata.
• Bozze per Aurora: avremo quattro settimane per abbozzare i nuovi articoli e gli aggiornamenti per quelli esistenti. Per identificare tutti le modifiche e le novità che necessitano di documentazione ci serviamo della pagina di Tracciamento dei rilasci.
• Tracciamento di Nightly: ci serviamo della pagina di Tracciamento dei rilasci per identificare tutti le modifiche e le novità che necessitano di documentazione. Questa operazione è un processo in divenire che continua fino alla fase Beta, ma, una volta su Aurora, le modifiche possibili coinvolgono soltanto l'eliminazione di caratteristiche dei prodotti.
• Archivio: dal momento che i nostri prodotti, servizi e documentazione si modificano con la progressione dei rilasci, viene utilizzato questo intervallo anche per valutare se esistano articoli
  • Obsoleti per modifiche ai prodotti o servizi;
  • Obsoleti a causa dell'esiguo numero di visite rispetto alla totalità degli utenti.

Ciclo della documentazione: settimane 5 e 6

• Aggiornamento di Release: verrà rilasciata una nuova versione dei prodotti Mozilla cosicché, se necessario, dobbiamo essere pronti a tornare sul lavoro fatto ed eseguire aggiustamenti alla documentazione basandoci sul riscontro prodotto dal forum di supporto.
• Completamento di Beta: una volta che Aurora viene spostato su Beta, avremo due settimane per completare gli articoli in bozza. Durante questa fase verranno eseguite queste operazioni:
  • Aggiunta di immagini e filmati (se necessario)
  • Revisione e approvazione degli articoli
  • Contrassegno della versioen finale come pronta per la localizzazione
• Inizio del tracciamento della nuova Nightly: una nuova versione sarà disponibile nel canale Nightly.

Come rimanere aggiornati sullo stato dei lavori?

• Mozilla Support (SUMO) blog: in questo blog compaiono gli ultimi aggiornamenti di progetto e di sviluppo.
• Pagina dei collaboratori: un'altra importante fonte di informazioni.
• Discussioni della comunità di SUMO: in questo spazio i collaboratori possono discutere tra loro.
• forum degli articoli della KB: qui trovano spazio le discussioni generali sullaKB.
• Forum di localizzazione: in questo forum si discute della localizzazione di SUMO.

Migliorare gli articoli

Il miglioramento della Knowledge Base probabilmente costituisce il 90% del nostro lavoro. Con centinaia di articoli a disposizione, c'è sempre qualcosa da migliorare. Ci sono tre modi per rendere un articolo migliore:

• Aggiornarlo: gli aggiornamenti di prodotto e di servizi spesso introducono novità importanti e modifiche all'utilizzo. Le istruzioni dovrebbero sempre applicarsi all'ultima versione stabile.
• Correggerlo: alcuni collaboratori hanno il dono di saper trovare gli erorri che i correttori ortografici dei programmi non trovano. C'è sempre bisogno di:
  • Correggere l'ortografia, la grammatica e la puntaggiatura
  • Risolvere i problemi di stile e formattazione (vedere Writing guide for Knowledge Base articles, Come utilizzare l'istruzione For e Come utilizzare i modelli per le linee guida)
• Renderlo più comprensibile:
  • Trovare un modo più semplice per esprimere un concetto complicato o non molto chiaro
  • Aggiungere immagini per aiutare la comprensione dell'articolo
  • Aggiungere filmati

What is the process for editing an article?

At a minimum, all you have to do is click Edit Article, make some changes and submit it for review. The full process looks like this:

1. Go to the Need Changes section of the Contributor Dashboard
2. From comments that describe what needs to be done, choose an article. Expand Editing Tools and take a look at the discussion in order to have information pertinent to this article.
3. Edit the article. See How to write knowledge base articles for style tips.
   • Use the Preview Content button to check your changes.
4. Click the Submit for Review button to save your changes. Your edit will be listed in the Unreviewed Changes section of the Contributor Dashboard.

If it's taking a long time to get a review you can ping michaelverdi in the #sumo IRC channel or via email.

If the reviewer doesn't approve the article they will post their reasons and feedback in the Discussion page thread for the article. Sometimes, they will also create a new revision based on yours and add or change things.

You (or anyone else) can create another revision and make more changes. It generally takes a few rounds to get things right.

Creating a new article

If you think there's an article that we need to add to the Knowledge Base, here's how to get it done.

1. Create a new article and fill out the form using the source for another article as a guide.
2. Draft the article content.
3. Check your work using the Preview Content button.
4. Click the Submit for Review button and include the reason for drafting the article in the comment.
   • Doing this gets the article on the KB Dashboard to let people know that the article is waiting for editing or review.
   • The article won't be public until it's been reviewed and approved.

Style

We want Mozilla Help to be usable by all users. This means we're writing for a general audience rather than one very familiar with computer techniques and terminology.

• The person you're writing for doesn't know how to change preferences or add a toolbar button without step-by-step instructions.
• Assume that people haven't changed any of the default product or operating system settings.
• Conversational writing style – Use an informal, active style similar to the way you'd speak to someone in person.
• Images and video – Using images and video to explain things along with text is not only the next best thing to being there to help in person, they are an easy way of including multiple learning styles and repetition.

For more, see Writing guide for Knowledge Base articles.

Markup

Our wiki uses MediaWiki syntax along with a few special things for styling buttons, keys, menus, etc. See the Sintassi Wiki for a list and examples.

{for}

Come utilizzare l'istruzione For contains instructions and examples for showing and hiding instructions for different Firefox versions and operating systems.

Templates

We have a list of templates that we use in articles so that the same bit of instruction doesn't have to be re-written, localized and kept in sync across multiple articles. Come utilizzare i modelli explains how it works.

Screenshots & Screencasts

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

Desktop Priority

1. Windows - with about 90% of our users on Windows this is a no-brainer. For now we should be making screenshots of Windows 7. When we add support for Windows XP, we'll want to add specific screenshots for it.
2. Mac - the current version is 10.8 (Mountain Lion).
3. Linux - use Ubuntu for screenshots.

Mobile

1. Android - 4.0 Ice Cream Sandwich.

Adding and removing articles

Proposing new articles

Our knowledge base is what makes our entire support effort scale to serve hundreds of millions of Firefox users. The most efficient thing we can do is answer people's questions about Mozilla's products and services with an article. But articles don't come without a cost. Each one has to be written, localized and maintained. With many features and issues already documented it's often a better use of our collective time to make existing articles better. Before you run off creating new articles like a madman, let's go over some things you should consider first:

Do we really need this article?
These are the main reasons why we add a new article to the Knowledge Base though it often makes more sense to update or add to an existing article.

• New features - User facing features that are likely to generate a lot of interest and questions from users. This may be an inherent aspect of the feature, a result of marketing and in-product links or a combination of the two.
• New issues - Issues that have many recent threads and votes in the support forum.
• High impact - Critical, time sensitive issues that need temporary documentation (e.g. Pogo.com and other Java pages don't work)

Archiving articles

We'll periodically archive knowledge base articles to keep our focus on users' most pressing items. As we release Mozilla's products 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 Segnalibri or Impostare la pagina iniziale) that will stay around for a long time, but there will be others that become obsolete or not of concern for users. Ideally, we should have about 200 articles. That will allow us to document things in enough detail while being small enough to maintain and localize.

How it works:
Contributors with reviewer privileges can mark an article as obsolete by editing the description section of an article. 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. If we've made a mistake, it's as easy as clicking a checkbox to get the article back on the dashboards.

Factors to consider before archiving an article:

• Low views - Generally, articles with less than about 1500 visits/month.
• Few recent reports - Issues that have relatively few recent threads and votes in the support forum.
• Low impact - Removal of the article is not likely to cause or exacerbate a serious issue.
• Changes to products and services - Instances where an issue has been fixed or a change in the behavior has made something obsolete.

Article review guidelines

Holy cow! This article is already too long so Article review guidelines is a separate article.