Gentoo Logo

Politica della Documentazione di Gentoo Linux

Indice:

1.  Introduzione

Introduzione

Il team di Documentazione di Gentoo Linux aspira a creare una documentazione particolarmente professionale che sia immediatamente chiara e concisa all'utente finale. Per compiere questo obiettivo, abbiamo delle regole molto specifiche e guide di riferimento che la nostra documentazione deve seguire prima che sia pubblicata sul nostro sito, o da altre parti.

Argomenti Trattati

Questa politica tratterà i seguenti argomenti:

  • Organizzazione del Team addetto al Progetto di Documentazione
  • Guide di Riferimento della Documentazione
  • Iscrizione al Team di Documentazione

2.  Organizzazione del Team addetto al Progetto di Documentazione

Organizzazione

Il Team addetto al Progetto di Documentazione di Gentoo consiste di redattori e autori, che lavorano ai nostri molti documenti e alle loro traduzioni. Come molti altri progetti Gentoo, sono condotti da un capo progetto il cui lavoro ulteriore consiste nel tenere una visione d'insimee del gruppo e delle sue risorse (come occuparsi del reclutamento quando necessario e prendere le decisioni finali quando l'accordo intorno a questioni diguardanti la documentazione non può essere trovato in altro modo).

Quando il Team per la Documentazione Gentoo avvia qualsiasi sottoprogetto, si troveranno gli obiettivi nella GDP Project Webpage (in inglese, NdT) insieme ai rispettivi capi progetto.

Membri del Team del Progetto di Documentazione

Ogni membro del Progetto di Documentazione di Gentoo deve essere iscritto alla mailing list gentoo-doc@gentoo.org. Questa mailing list sarà usata per discutere su tutti gli aspetti relativi alla documentazione. La mailing list è aperta a tutti coloro che sono interessati, sviluppatori o meno.

Ogni membro del Progetto di Documentazione di Gentoo deve essere parte dell'alias docs-team@gentoo.org. Questo alias è usato solo da bugs.gentoo.org per informare il team della documentazione sui bug che riguardano la Documentazione di Gentoo. Ci si può aggiungere modificando /var/mail/alias/misc/docs-team su dev.gentoo.org. Non utilizzare questo indirizzo per prendere contatto col Team - è possibile contattarci alttraverso la mailing list, IRC o scrivendo al capo progetto o a qualisiasi altro membro.

Ogni membro del Team di Documentazione di Gentoo sono frequentemente online su #gentoo-doc su irc.freenode.net ogni volta che è online.

A seconda delle proprie responsabilità, un membro può avere un accesso limitato al CVS a cvs.gentoo.org. Persone interessate che non sono sviluppatori possono usare il server CVS anonimo, per aiutarci con la documentazione. Contenente gli stessi file del server CVS principale, ma con un ritardo di aggiornamento di qualche minuto.

Team di Traduzione della Documentazione

Ogni lingua dovrebbe essere sostenuta da un team ufficiale di traduzione. Questo team è guidato da un coordinatore e, non sempre, da un vice coordinatore, i quali hanno accesso al commit sul CVS. L'organizzazione delle traduzioni è gestita dal capo progetto secondo le necessità, secondo le politiche generali delle traduzioni.

Se viene inviato come contributo un documento tradotto, ma la lingua non è supportata, il Team di Documentazione di Gentoo lo pubblicherà così com'è. I collegamenti a questo tipo di documenti non verranno inseriti nel sito web finchè non si formerà un team ufficiale di traduzione di quella lingua, ma i documenti in sè saranno comunque disponibili nel sito e in CVS.

Per ulteriori informazioni sulle traduzioni della documentazione di Gentoo, consultare la Guida alla traduzione della documentazione di Gentoo e GDP Internationalisation Subproject.

3.  Guide di Riferimento della Documentazione di Gentoo

Aspetti Legali

Ogni documento pubblicato dal Progetto di Documentazione di Gentoo deve avere come licenza la Creative Commons Attribution-ShareAlike License, preferibilmente all'ultima versione (sebbene anche le versioni precedenti siano supportate).

Ogni documento deve avere il seguente tag nel proprio codice sorgente GuideXML tra i tag </abstract> e <version>:

Codice 3.1: Avviso di licenza per la Documentazione di Gentoo

</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/3.0 -->
<license version="3.0"/>

<version>...</version>

Se viene usata la versione 2.5, il tag può essere o <license /> o <license version="2.5" />. In entrambi i casi il commento deve essere aggiornato per far riferimento all'URL della versione appropriata.

Bug e Aggiornamenti

Ogni bug riportato su bugs.gentoo.org dovrebbe essere gestito il più velocemente possibile. Se un bug non può essere gestito in modo tempestivo, colui che ha riportato il bug dovrebbe essere informato, usando un commento sul bug e il bug stesso dovrebbe essere registrato nel file metadoc.xml, se applicabile.

Ogni volta che un membro del Team di Documentazione di Gentoo si prende cura di un bug, dovrebbe assegnare il bug a sè stesso, e assicurarsi che docs-team@gentoo.org sia nella lista Cc. Un membro del Team di Documentazione non può autoassegnarsi un bug già assegnato ad un altro membro senza il consenso del responsabile del progetto.

Sviluppo del Documento

Ogni documento che il Team di Documentazione di Gentoo sviluppa può essere elaborato come ritiene più opportuno. Tuttavia, quando il documento è finito, dovrebbe essere trasformato in GuideXML e reso disponibile nell'infrastruttura CVS di Gentoo. Deve anche essere registrato nel file metadoc.xml, se possibile.

Quando un nuovo documento è iniziato o è necessario un grande cambiamento, dovrebbe essere inserito su bugs.gentoo.org un bug riguardante lo sviluppo di questo documento. Se nel database c'è già un bug che richiede un cambiamento alla documentazione, non bisogna inserirne uno di nuovo. Anche piccoli cambiamenti, grammaticali, di sintassi, non richiedono l'inserimento di un un bug su bugs.gentoo.org.

Tutti i cambiamenti nei contenuti del documento, tranne le correzioni di errori di ortografia nel testo o nei commenti agli elenchi di codice, dovrebbero portare ad un incremento del numero di versione e della data. Notare che la modifica di un blocco di codice dovrebbe certamente produrre un incremento del numero della versione e della data.

Tutti i cambiamenti nella formattazione di XML dovrebbero portare ad una modifica della versione e della data soltanto nel caso in cui cambi l'impaginazione del documento.

Le versioni dovrebbero essere sempre numeri interi, così un incremento di versione della versione 2 porta alla versione 3. Documenti che per ragioni storiche usano ancora la versione con numero maggiore e minore dovrebbero essere convertiti all'intero successivo al successivo aggiornamento, così la versione 3.2 diventerà la versione 4.

Ogni aggiornamento di una traduzione dovrebbe usare alla lettera le informazioni di versione e data del documento principale inglese, in modo che le traduzioni completamente sincronizzate abbiano la stessa versione e data.

Revisione e Commit

Per mantenere alto il ciclo di sviluppo della documentazione, i cambiamenti di natura tecnica o intrusiva possono essere inseriti subito nel documento. Questo è permesso se il redattore è sicuro che i cambiamenti siano corretti dal punto di vista funzionale. Se non si è sicuri (per esempio se un utente ha detto come riparare un bug ma non è possibile verificarlo direttamente), far rivedere il cambiamento ad una terza persona, in modo che possa verificarlo.

Grandi cambiamenti, tecnici o intrusivi, devono essere accompagnati da un bug report su http://bugs.gentoo.org. Il numero del bugreport deve essere menzionato nel log del CVS, per permettere il tracciamento dei cambiamenti.

Se la correzione è costituita sia da cambiamenti di contenuto che da cambiamenti del codice interno, entrambi devono essere applicate ma separatamente, cosìcchè i traduttori possano analizzare più facilmente i cambiamenti importanti (contenuto) e ignorare quelli di codice.

Sanzioni

Condotte irregolari degli sviluppatori non sono state un problema finora. Tuttavia dovrebbe essere osservato che sviluppatori della documentazione che abusano della loro posizione riguardo a

  • fornire deliberatamente informazioni errate a utenti o sviluppatori
  • scrivere deliberatamente documentazione non corretta
  • corrompere deliberatamente i documenti
  • andare deliberatamente contro le decisioni prese dalla politica di Gentoo o dal consenso della mailinglist della documentazione di Gentoo
  • non svolgere nessun compito per un lungo tempo senza informare il GDP

saranno segnalati al progetto Gentoo Developer Relations.

4.  Iscrizione al Team di Documentazione

Contributori, Autori, Traduttori

Chiunque sia interessato a contribuire alla documentazione, a pubblicare una documentazione esistente, a scriverne una nuova o a tradurla, può inviare il proprio contributo, che ovviamente sarà benaccetto. Non ci sono regole o limitazioni a riguardo. Assicurarsi di essere iscritti a gentoo-doc@gentoo.org e di aver letto completamente e compreso questa linea di condotta.

Processo di reclutamento

Il Progetto di Documentazione usa il rigoroso processo di reclutamento spiegato qui di seguito. È stato scelto per assicurare che chi entra nel gruppo conosca bene la Politica di Documentazione Gentoo e lo Stile di Codice Gentoo. Risulta abbastanza efficace anche se molti contributori lo considerano troppo difficile.

Questo processo è solo per le richieste al Gentoo Documentation Repository attraverso il CVS. Per essere elencati come mantenitore o punto di contatto per un certo documento o per un certa gamma di essi non occorre il ruolo di sviluppatore.

Fase 1: Contributi

Nessun processo di reclutamento comincia senza vedere i contributi fatti al Progetto di Documentazione Gentoo. Il numero di contributi deve essere ampio per assicurare una buona conoscenza del GuideXML, Stile di Codice e la Politica. Il periodo di contribuzione deve ampio anche per consentire a chi contribuisce di valutare se ha la possilità di offrire supporto continuo al Progetto Documentazione Gentoo.

Un aggiornamento è un cambiamento considerevole a un documento, una traduzione o altro, scritto o redatto dal contributore e applicato dopo la revisione da uno sviluppatore.

Se si pensa di avere un buona quantità di contributi contattare il capo progetto del Progetto di Documentazione Gentoo. Egli chiederà dei dati ed altre informazioni e predisporrà il passaggio alla fase successiva.

Fase 2: Inizio del Processo di Reclutamento

Durante questo periodo, le patch proposte non verranno più redatte da uno sviluppatore della documentazione, ma potranno essere o accettate così come sono o rifiutate. La recluta viene inoltre assegnata ad uno sviluppatore di documentazione a tempo pieno (il mentore) che lo guiderà attraverso queste ultime fasi.

La qualità dei contributi in questa fase è molto importante - ogni patch che non segue la Politica di Documentazione, Stile di Codice o altre linee guida che rovinano il documento è impugnata dalla recluta stessa con l'aiuto del mentor.

Durante questo periodo, la recluta deve:

  • imparare bene i funzionamenti interni di Gentoo. Questo è richiesto poiché verrà chiesto di rispondere al Quiz per lo Staff di Gentoo.
  • rispondere al Quiz del Progetto di Documentazione Gentoo. È necessario passare questo quiz (rispondendo correttamente a tutte le domande), prima di continuare con la prossima fase.

Fase 3: Reclutamento Gentoo

Quando la fase 2 è terminata, il capo progetto contatterà Developer Relations e darà il via finale per il processo di reclutamento Gentoo dopo il quale verrà fornito l'accesso ai necessari servizi infrastrutturali Gentoo (come il repository della documentazione).

Reclutamento degli Sviluppatori Gentoo

Se la recluta è già Sviluppatore Gentoo, viene seguito lo stesso processo di reclutamento, ma il quiz per lo stafff non è più necessario. Tuttavia, il Quiz del Progetto di Documentazione Gentoo è ancora obbligatorio.



Stampa

Aggiornato il 29 novembre 2011

La versione originale di questo documento è più recente ed è stata aggiornata il 31 marzo 2013

Oggetto: Questo documento contiene la Politica della Documentazione di Gentoo, ovvero il documento base che tutti gli sviluppatori e i Contributori della Documentazione di Gentoo dovrebbero conoscere ed esercitare.

Xavier Neys
Autore

John P. Davis
Autore

Sven Vermeulen
Autore

Donnie Berkholz
Redazione

Stefano Pacella
Traduzione

Team Italiano
Traduzione

Davide Cendron
Traduzione

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.