El equipo de documentación de Gentoo Linux aspira a crear documentación excepcionalmente profesional que sea totalmente clara y orientada al usuario final. Para cumplir esta meta, tenemos reglas muy específicas y pautas que toda la documentación debe seguir antes de ser publicada en nuestro sitio web, o en cualquier otro sitio.
Esta política cubre los siguientes asuntos:
2. Organización del Equipo del Proyecto de Documentación
El equipo del Proyecto de Documentación de Gentoo se divide en muchos equipos más pequeños que trabajan en total cooperación entre ellos. Cada equipo pequeño representa un equipo desarrollo activo de un Subproyecto de Documentación de Gentoo.
Para las tareas directivas diarias, el proyecto de documentación de Gentoo tiene un gerente de operaciones. Esta persona se centra en todas las tareas relacionadas con la documentación que son a más corto plazo. El gerente de operaciones y el estratégico pueden ser el mismo, si el gerente estratégico así lo desea.
Estos cargos actualmente son desempeñados por las siguientes personas:
| Posición | Nombre del desarrollador | Apodo del desarrollador |
| Gerente estratégico | Xavier Neys | neysx |
| Gerente de operaciones | Xavier Neys | neysx |
Cada subproyecto del Equipo de Documentación de Gentoo se muestran en la página del GDP, junto con sus respectivos gerentes estratégicos.
La decisión de añadir subproyectos está en manos del gerente estratégico.
Miembros del equipo del proyecto de documentación
Cada miembro del Proyecto de Documentación de Gentoo debe estar subscrito a la lista de correo gentoo-doc@gentoo.org. Esta lista será utilizada para discutir todos los temas relacionados con la documentación. Estará abierta a todas las partes interesadas, sean desarrolladores o no.
Cada miembro del Proyecto de Documentación de Gentoo debe estar suscrito al alias docs-team@gentoo.org. Este alias es utilizado solamente por bugs.gentoo.org para informar al equipo de documentación acerca de los errores relacionados con la documentación de Gentoo. Usted puede añadirse editando /var/mail/alias/misc/docs-team en dev.gentoo.org.
Cada miembro del Equipo de Documentación de Gentoo debería estar disponible en el canal #gentoo-doc en irc.freenode.net siempre que esté conectado.
Dependiendo de sus responsabilidades, todo miembro puede tener acceso CVS limitado a cvs.gentoo.org. El acceso total a CVS está restringido a los desarrolladores de Gentoo. Un servidor anónimo CVS esta disponible. Contiene los mismos ficheros que nuestro servidor CVS con unos minutos de retraso.
Equipos de traducción de la documentación
Cada idioma debería ser llevado por un equipo oficial de traducción. Dicho equipo está dirigido por un Jefe de Traducción y, tal vez, un Subjefe de Traducciónr, teniendo ambos acceso a cambios en el CVS. Si por cualquier motivo el Jefe de Traducción no puede llevar a cabo sus tareas, el Subjefe de Traducción estará al cargo. Si el Subjefe tampoco esta disponible, el mentor o mentores estarán a cargo del idioma.
Si se aporta una traducción nueva, pero el idioma no está soportado, el equipo de documentación de Gentoo la publicará tal como esté. En ese caso, el documento permanecerá sin enlazar hasta que se forme un equipo de traducción oficial de ese idioma, sin embargo estará disponible en nuestro sitio y en CVS.
Cuando un idioma está soportado oficialmente, pero el equipo no tiene ningún miembro o nadie quiera tomar la responsabilidad del Jefe de Traducción, todos los enlaces a los documentos serán eliminados de ese sitio. Sin embargo, los documentos estarán disponibles en caso de que el idioma vuelva a estar oficialmente soportado.
Para más información sobre las traducciones de la documentación de Gentoo, por favor consulte la Guía para los traductores de documentación Gentoo y la página del Subproyecto de Internacionalización GDP(en inglés).
3. Pautas de Documentación Gentoo
Todo documento publicado por el Proyecto de Documentación de Gentoo debe estar bajo la licencia Creative Commons Attribution-ShareAlike License.
Todo documento debe tener la siguiente etiqueta en el código de su guía XML entre las etiquetas </abstract> y <version>:
Listado de Código 3.1: Aviso sobre la licencia de Documentación Gentoo |
</abstract>
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
<version>...</version>
|
Cada error reportado en bugs.gentoo.org debería ser tratado tan rápido como sea posible. Si un error no puede ser tratado de manera oportuna, quien haya reportado ese error debería ser informado de ello poniendo un comentario en el error y debería registrarse en el archivo metadoc.xml si fuera necesario. El gerente táctico u operacional puede decidir que error tiene mayor prioridad y debería ser tratado antes que cualquier otra tarea sea asignada.
Siempre que un miembro del Equipo de Documentación de Gentoo se encarga de un error, debe asignarse a sí mismo el error, pero asegurándose de que docs-team@gentoo.org está en la lista de Cc. A menos que sea con el consentimiento del gerente operacional, un error no puede ser eliminado por otro miembro del Equipo de Documentación de Gentoo sin su aprobación.
Todo documento que el equipo de documentación de Gentoo desarrolla, puede ser desarrollado según las partes intervinientes crean conveniente. Sin embargo, cuando el documento está acabado, debe ser transformado en GuíaXML y puesto en la infraestructura de CVS de Gentoo. También debe registrarse en el archivo metadoc.xml si fuera necesario.
Cuando se empieza un nuevo documento o se necesita un cambio grande, un aviso debe ser archivado en bugs.gentoo.org en lo referente al desarrollo del documento. Si ya existe un aviso en la base de datos que solicita un cambio en la documentación, no hay que archivar un nuevo aviso. Cambios gramaticales, sintácticos o pequeños tampoco requieren el archivo de un aviso en bugs.gentoo.org.
Todos los cambios en el contenido del documento, excepto correcciones de errores en el texto o en los comentarios de los listados de código, deben llevar al aumento de número de versión (y fecha). Observe que el cambio de los listados de código debe causar un aumento de número y fecha de la versión.
Todos los cambios en el formato XML deben llevar a un salto de la versión (y fecha) sólo en caso de que la disposición del HTML del documento cambie.
Incrementar o no el número mayor de versión en lugar del número menor de versión u otro, es cosa del editor.
Toda actualización de una traducción debe copiar la información textual de la nueva versión del documento maestro en inglés para sincronizar totalmente las traducciones y que así tengan la misma información de versión y fecha.
Para mantener un ciclo alto de desarrollo de la documentación, los cambios técnicos o intrusivos de los documentos pueden ser propagados inmediatamente al documento, si el editor está 100% seguro que serán correctos y funcionarán. Si no está 100% seguro (por ejemplo, porque un usuario le ha dicho cómo hacerlo, pero no puede verificarlo), haga revisar el cambio a un desarrollador de Gentoo que pueda verificarlo.
Cambios de mucho volumen, técnicos o intrusivos deben ir acompañados de un aviso en http://bugs.gentoo.org. Este número de error debe ser mencionado en el registro del CVS para permitir volver atrás en los cambios.
Si un cierre de aviso consiste en cambios tanto de contenido, como internos, ambos cambios deben ser enviados (commit) separadamente para que así los traductores puedan ver fácilmente los cambios importantes (contenido) e ignorar los cambios de codificación.
Si el documento en cuestión es una traducción, el Jefe de Traducción del idioma afectado es responsable del documento. Únicamente el Jefe de Traducción y su sustituto pueden hacer envíos del documento al repositorio CVS. Sin embargo, si el Jefe de Traducción está en ese momento "en entrenamiento", su mentor deberá enviar los cambios.
Aunque esto nunca ha sido necesario, sigue siendo importante enumerarlo en la política - a pesar de que es odioso. De todas formas, los desarrolladores de documentación que empleen mal su posición:
serán informados al proyecto Developer Relations de Gentoo.
4. Reclutamiento del equipo de documentación
Colaboradores, autores, traductores
Cualquiera interesado en contribuir documentación, corregir la existente, escribir nueva documentación o traducirla, es bienvenido a unirse al equipo. No hay reglas o cadenas unidas a ello. Sólo asegúrese de que está suscrito a gentoo-doc@gentoo.org y ha leído y comprendido toda la política.
El proyecto de documentación tiene un estricto proceso de reclutamiento indicado abajo. Este proceso no puede ser modificado bajo ninguna circunstancia. Hemos optado por el proceso de reclutamiento para asegurarnos de que la persona reclutada está bien informada acerca de la política de documentación de Gentoo y sobre el estilo de codificación de Gentoo. Ha resultado ser muy efectiva aunque muchos colaboradores la ven como una enorme barrera a cruzar.
Este proceso de reclutamiento esta pensado únicamente para peticiones al repositorio de documentación de Gentoo a través de CVS. Ser listado como mantenedor o contacto para un cierto documento o conjunto de documentos es realizado medianta una simple petición al gerente de operaciones o al jefe de proyecto.
Ningún proceso de reclutamiento comienza sin investigar las contribuciones realizadas al proyecto de documentación de Gentoo. El número de contribuciones debe ser lo suficientemente grande para asegurar un buen conocimiento de la guía XML, y el estilo y la política de codificación. El período de contribuciones debe ser igualmente largo para informar al colaborador acerca del consumo de tiempo y la presión que implica.
El número de contribuciones y el período de las mismas que se requieren, depende de la posición que el colaborador está reclamando. Aunque es difícil escribir estas medidas en números, la siguiente tabla debería ofrecer una visión general. La decisión final, sin embargo, recae en las manos del gerente operacional.
| Posición | Actividad Mínima | Período Mínimo |
| Desarrollador a tiempo completo | 2 actualizaciones por semana | 1 mes |
| Desarrollador a tiempo parcialr | 4 actualizaciones al mes | 1 mes |
Una actualización conlleva la modificación de cualquier documentación, traducción y otras, completamente escritas por el colaborador y publicada después de ser revisada por algún desarrollador de documentación. El período está fijado -- aumentar las contribuciones no decrementa el período. De igual modo no medimos el reparto del número de contribuciones a lo largo del tiempo para asegurarnos de que el colaborador no genera una avalancha de contribuciones y entonces espera hasta que la fase ha concluido.
Sin esta fase, no podemos saber si el colaborador comprende que requiere tiempo llegar a ser un desarrollador de documentación. La validación de esta actividad se muestra en los informes de bugzilla.
Cualquier petición de acceso a CVS que no permita las actividades de desarrollo descritas en la tabla de arriba, no serán tenidas en cuenta.
Si cree que ha mostrado suficiente cantidad de contribuciones, contacte con el gestor operacional del proyecto de documentación de Gentoo. Le pedirá sus datos y otra información, y entonces preparará la siguiente fase para su comienzo.
Fase 2: Comienzo del proceso de reclutamiento
Durante este período, que es básicamente el mencionado en la tabla, los parches enviados ya no son editados por un desarrollador de documentación, sino que son enviados tal cual o rechazados. El reclutamiento es asignado a un desarrollador a tiempo completo (el mentor) que le guiará por estas últimas fases.
La calidad de las contribuciones son, en esta fase, lo más importante -- cada parche que no sigue la política de documentación, el estilo de codificación u otras pautas, conlleva que el documento sea rechazado.
Durante este pediodo:
Fase 3: Reclutamiento en Gentoo
Cuando la fase 2 ha concluido, el gestor operacional contactará con Developer Relations y le dará el visto bueno final al proceso de reclutamiento en Gentoo, después del cual se le hará entrega de una dirección de correo de gentoo y será adscrito a uno o más subproyectos.
El contenido de este documento está registrado bajo los términos de la licencia Creative Commons - Reconocimiento / Compartir Igual