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 la nostra 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 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 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>:
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. 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. 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. 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. 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
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 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. 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:
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. I contenuti di questo documento sono rilasciati sotto la licenza Creative Commons - Attribution / Share Alike. |
|