Directriz de Documentación de Gentoo LinuxEl 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 nuestra documentación debe seguir antes de ser publicada en nuestro sitio web, o en cualquier otro sitio. Esta directriz cubre los siguientes asuntos:
2. Organización del Equipo del Proyecto de Documentación El equipo del Proyecto de Documentación de Gentoo se compone de editores y autores que trabajan en nuestra documentación principal y en sus traducciones. Al igual que otros muchos proyectos de Gentoo, está dirigido por un líder del proyecto cuyo trabajo adicional es cuidar del equipo y sus recursos en general (así como centrarse en el reclutamiento cuando éste sea necesario y también tomar las decisiones finales cuando el consenso sobre asuntos relacionados con la documentación no puede ser alcanzado de otro modo). Cuando el equipo de documentación de Gentoo lanza un subproyecto, encontrará sus enunciados de misión en nuestra página del proyecto de documentación de Gentoo , junto con sus líderes de proyecto respectivos. 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. Puede añadirse editando /var/mail/alias/misc/docs-team en dev.gentoo.org. Por favor, no utilice esta dirección para contactar con el equipo, puede contactar con nosotros a través de las listas de correo, IRC o escribiendo al líder del proyecto o a cualquier otro miembro. Los miembros Equipo de Documentación de Gentoo normalmente están en línea en el canal #gentoo-doc en irc.freenode.net. Dependiendo de las asignaciones y de sus responsabilidades, un miembro puede tener acceso CVS a cvs.gentoo.org. Las personas interesadas que no sea desarrolladores pueden utilizar el servidor anónimo CVS para ayudar con la documentación. 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 Responsable de traducción y, tal vez, un Responsable de traducción de respaldo, teniendo ambos acceso a cambios en el CVS. La organización de las traducciones es gestionada por el líder del proyecto de traducción de cada idioma, tal y como lo considere, siempre que las traducciones enviadas sigan estas directrices. 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. 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 del GDP. 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, preferentemente la última versión (aunque se admiten también versiones anteriores). Todo documento debe tener la siguiente etiqueta en el código de su guía XML entre las etiquetas </abstract> y <version>:
Si se utiliza la versión 2.5, la etiqueta puede ser <license /> o <license version="2.5" />. En ambos casos, se debe actualizar el comentario para referirse al URL correcto para la versión. Cada informe de 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 escribiendo un comentario en el informe de error. 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, a menos que el líder del proyecto lo permita. Todo documento realizado por el equipo de documentación de Gentoo, puede ser desarrollado según las partes intervinientes crean conveniente. Sin embargo, cuando el documento está acabado, debe ser transformado en Guía XML 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) solo en caso de que la disposición del HTML del documento cambie. Las versiones de los documentos deben ser siempre tratadas como números enteros, por lo tanto, un incremento en la versión 2 nos llevará a la versión 3. Versiones antiguas que utilicen una sintaxis con versiones mayores y menores, deberán ser convertidas al siguiente entero cuando se produzca la siguiente actualización, por lo tanto, la versión 3.2 se convierte en la versión 4. 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 de que serán funcionará correctamente. Si no está 100% seguro (por ejemplo, porque un usuario le ha dicho cómo hacerlo, pero no puede verificarlo), deberá pedir a una tercera persona que pueda verificarlo que los cambios se han realizo correctamente. 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. Nunca hemos tenido problemas con la conducta de nuestros desarrolladores. Sin embargo, se debe advertir que los desarrolladores de la documentación que empleen mal su posición para:
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. Solo asegúrese de que está suscrito a gentoo-doc@gentoo.org y ha leído y comprendido esta directriz. El proyecto de documentación sigue el proceso de reclutamiento indicado abajo. Hemos optado por este proceso para asegurarnos de que el candidato está bien informado acerca de la directriz de documentación de Gentoo y de su estilo de codificación. Hemos comprobado que este proceso es bastante efectivo aunque muchos contribuyentes lo ven como una gran barrera a cruzar. Este proceso de reclutamiento esta pensado únicamente para peticiones al repositorio de documentación de Gentoo a través de CVS. Para ser listado como mantenedor o contacto para un cierto documento no es necesario tener acceso como desarrollador. 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 directriz de codificación. El período de contribuciones debe ser igualmente largo para permitir que el contribuyente decida si puede ofrecer soporte continuo al proyecto de documentación de Gentoo. Una actualización conlleva la modificación de cualquier documentación, traducción y otros documentos completamente escritos o editados por el contribuyente y enviado para publicación por un desarrollador de la documentación después de su revisión. Si cree que ha realizado una cantidad suficiente de contribuciones, contacte con el líder del proyecto de documentación de Gentoo, el cual revisará sus contribuciones y los periodos de tiempo en las que las ha realizado (o delegará estas acciones a otro miembro del equipo de documentación). Le pedirá sus coordenadas y otra información y preparará la siguiente fase. Fase 2: Comienzo del proceso de reclutamiento Durante este período, los parches enviados no serán editados por ningún desarrollador de documentación. Éstos serán enviados para publicación o rechazados. En esta fase, se asigna un desarrollador de documentación (mentor) al candidato que le guiará en la última fase. La calidad de las contribuciones son, en esta fase, lo más importante. Cada parche que no siga la directriz de documentación, el estilo de codificación u otras pautas, conlleva que el documento sea supervisado por el propio candidato con ayuda de su mentor. Durante este periodo, se recomienda al candidato aprender el funcionamiento interno de Gentoo. Esto es necesario ya que a él o a ella se le pedirá más adelante que rellene las preguntas para el staff de Gentoo (Staffing Quiz). También se recomienda, pero no es obligatorio, rellenar las preguntas del Proyecto de Documentación de Gentoo (Gentoo Documentation Project Quiz). Esto ayudará al candidato en el aprendizaje sobre cómo funciona el Proyecto de Documentación de Gentoo. Si más adelante el líder del Proyecto de Documentación de Gentoo cree que el candidato (o para entonces el editor o autor) no posee los conocimientos adecuados, puede solicitar que trabaje en las preguntas. Fase 3: Reclutamiento en Gentoo Cuando la fase 2 ha concluido, el líder del proyecto contactará con Developer Relations y le dará el visto bueno final al proceso de reclutamiento en Gentoo, después del cual se le concederá acceso a los servicios de infraestructura Gentoo que necesite (como por ejemplo al repositorio de la documentación). Reclutamiento de candidatos que ya sean desarrolladores Gentoo En caso de que el candidato ya sea un desarrollador Gentoo, se seguirá el mismo proceso de reclutamiento, aunque, desde luego, no será necesario que rellene el Staffing Quiz. Sin embargo, se recomienda que se rellenen las preguntas del Proyecto de Documentación de Gentoo (Gentoo Documentation Project Quiz). El contenido de este documento, a no ser que se especifique expresamente, está registrado bajo los términos de la licencia CC-BY-SA-2.5. Se aplican las Pautas de Utilización del logotipo y nombre de Gentoo. |
|