Politica della Documentazione di Gentoo LinuxIl 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 tutta la documentazione deve seguire prima che sia pubblicata sul nostro sito, o da altre parti. Questa politica tratterà i seguenti argomenti:
2. Organizzazione del Team addetto al Progetto di Documentazione Il Team addetto al Progetto di Documentazione di Gentoo è diviso in parecchi team più piccoli che operano in completa collaborazione tra loro. Ogni team più piccolo rappresenta un team attivo di sviluppo del Sottoprogetto di Documentazione di Gentoo. Per le mansioni direttive giornaliere il Progetto di Documentazione di Gentoo ha un responsabile operativo. Questa persona si tiene al corrente di tutte le mansioni relative alla documentazione che sono di più breve durata. Il responsabile operativo ed il responsabile strategico possono essere la stessa persona se il responsabile strategico lo desidera. Attualmente queste posizioni sono prese dalle seguenti persone:
I sottoprogetti del Team di Documentazione di Gentoo insieme ai loro rispettivi responsabili strategici sono elencati sul sito web GDP. La decisione sull'aggiunta di un sottoprogetto è nelle mani del responsabile strategico. 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. Ogni membro del Team di Documentazione di Gentoo dovrebbe essere disponibile 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. L'accesso completo al CVS può soltanto essere dato agli sviluppatori di Gentoo. È disponibile un server CVS anonimo, 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. Se per qualsiasi motivo il coordinatore non può adempiere alle proprie funzioni, è in carico il vice coordinatore. Se anche quest'ultimo non è disponibile, il (o i) mentore(i) sono incaricati per tale lingua. 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. Quando una lingua è supportata ufficialmente, ma il team non ha nessun membro che voglia prendersi le responsabilità di Responsabile Traduzioni, tutti i collegamenti ai documenti saranno rimossi dal sito. Tuttavia, i documenti saranno disponibili nel caso la lingua diventi di nuovo ufficialmente supportata. 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 Ogni documento pubblicato dal Progetto di Documentazione di Gentoo deve avere come licenza la Creative Commons Attribution-ShareAlike License. Ogni documento deve avere il seguente tag nel proprio codice sorgente GuideXML tra i tag </abstract> e <version>:
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. Il responsabile strategico o operativo può decidere che ad un bug venga data una priorità maggiore e debba essere trattato prima di qualunque altra operazione. 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 operativo. 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. L'incremento o meno della versione principale piuttosto della versione secondaria o di altro, spetta al redattore. 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. 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 funzionino. 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 uno sviluppatore di Gentoo, 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. Nel caso di una traduzione, il Responsabile Traduzioni per quella lingua è responsabile del documento. Solo il Responsabile Traduzioni e il suo aiutante possono fare il commit del documento nel repository CVS. Tuttavia, se il Responsabile Traduzioni è "in prova", il commit della modifica dovrebbe farla il relativo mentore. Condotte irregolari degli sviluppatori non sono mai state un problema. Dovrebbe essere reso noto che sviluppatori della documentazione che abusano della loro posizione riguardo a
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. Il Progetto di Documentazione ha un rigoroso processo di reclutamento spiegato qui di seguito. Questo processo non può essere deviato in nessuna circostanza. È 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 basta fare una semplice richiesta al Responsabile Operativo o al Responsabile del Progetto. 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 essere ampio. Il numero di contributi e il periodo dovrebbe dipendere dalla posizione al quale il contributore aspira. E' difficile scrivere i numeri per questo processo, la seguente tabella dovrebbe dare una panoramica generale. La decisione finale è presa dal Responsabile Operativo.
Un aggiornamento è un cambiamento considerevole a un documento, una traduzione o altro, scritto dal contributore e applicato dopo la revisione da uno sviluppatore. Il periodo è fisso - aumentare le documentazioni non diminuisce il periodo. Non viene fatta la media di ogni contributo per assicurare che il contributore non bruci il contributo e poi aspetti la fine della fase. Senza questa fase non si ha la certezza se il contributore conosca cosa vuol dire essere uno sviluppatore della documentazione. La validità di questa attività è seguita con i bugreport. Una richiesta per un accesso al CVS che non permette una attività di sviluppo come scritto nella tabella non è presa in considerazione. Se si pensa di avere un buona quantità di contributi contattare il Responsabile Operativo 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, che è più o meno uguale alla tabella summenzionata, 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 è rifiutata. Durante questo periodo:
Quando la fase 2 è terminata, il Responsabile Operativo contatterà Developer Relations e darà il via finale per il processo di reclutamento Gentoo dopo il quale verrà fornito un indirizzo e-mail e si verrà aggiunti a uno o più sottoprogetti. I contenuti di questo documento sono rilasciati sotto la licenza Creative Commons - Attribution / Share Alike. |
|
