Contribuir a Mejoras y Artículos de Documentos Expandidos
Este documento explica como funciona con el sistema de publicación utilizada para construir el sitio web de Documentación de Fedora. Le guiará a través de contribuir documentación existente así como crear conjunto de contenido completamente nuevo y publicarlos en los originales en inglés así como cualquiera de las traducciones posibles.
Hay muchas maneras de contribuir a la documentación de Fedora. Algunas están diseñadas para facilitar las contribuciones sin conocimientos técnicos sobre sistemas de gestión de contenido web (SGC) ni sobre cómo almacenar y gestionar sus contribuciones. La herramienta se encarga de todo esto por usted, permitiendo a los autores concentrarse en el tema en cuestión.
Por favor, consúltenos. Si encuentra una página de documentación con un error o inexactitud, utilice una de las herramientas de contribución informal que se describen a continuación para mejorarla. Si tiene alguna pregunta, no dude en contactar con el equipo de documentación.
Las herramientas de autoridad local está diseñada para proporcionar un entorno de trabajo potente para los autores expertos. Ellos realizan trabajo eficiente incluso en colecciones de texto interrelacionados grandes complejos. Estas herramientas son llevadas a cabo por autores expertos.
Como funciona
La documentación de Fedora utiliza Antora para crear y administrar el sitio web. La documentación es bastante estática, con actualizaciones ocasionales. Esto es precisamente en lo que Antora se especializa: recopila documentos de texto estáticos y los transforma en un sitio web completo, incluyendo navegación, enlaces, formato, posicionamiento, adaptación a diferentes dispositivos de salida, etc. Para más información general sobre el sistema de publicación Antora, consulte el sitio web Antora y la documentación de Antora.
Como escritor, te concentras en el contenido y escribes.
El procedimiento general
El principio de los cuatro ojos se aplica a la documentación de Fedora. Un autor diferente revisa cada contribución. Al completar su texto o modificarlo, el sistema crea una solicitud de «incorporación» o «fusión» para integrarlo en la documentación. Esto activa la revisión de otros autores, miembros del consejo o miembros comprometidos con la parte del cuerpo de la documentación en cuestión, iniciando una revisión e incluso inicializa una inclusión o un debate. La respuesta a la solicitud puede tardar de 2 a 3 días.
Algunos antecedentes técnicos
Fedora utiliza AsciiDoc para formato de texto en una manera simple y eficiente. Sigue de cerca los estilos de escritura naturales en notas en cada día para estructurar y resaltar. De esta manera, puede utilizar cualquier editor, incluyendo casi cualquier procesador de textos que pueda editar y guardar Texto AsciiDoc. Más acerca de esto a continuación.
El documento de texto AsciiDoc se almacena en una serie de repositorios Git. Este sistema es especialmente popular entre los desarrolladores de software, pero también es muy eficaz para gestionar documentos de texto. Git fomenta y facilita el uso del principio de «los cuatro ojos» mediante un «Flujo de trabajo de solicitud de extracción (o fusión)». Solo debe preocuparse por los detalles de este flujo de trabajo si desea configurar un entorno de trabajo local para contribuciones profesionales y frecuentes. Las demás herramientas se encargan de los pasos necesarios en segundo plano.
Requisitos previos
Solamente los requisitos para contribuir con la documentación de Fedora Docs son:
-
Cuenta de Fedora Account System (FAS).
-
Cuenta de GitLab
-
Debe haber firmado el Acuerdo de Colaborador del Proyecto Fedora desde FAS. Para firmar, vaya a su cuenta de Fedora, seleccione «Opciones» pulsando sobre su imagen de perfil en la esquina superior derecha y luego seleccione la pestaña «Acuerdos». Alternativamente, puede encontrarlo aquí, sustituyendo su nombre de usuario: https://accounts.fedoraproject.org/user/su-nombreusuario/settings/agreements/
-
Conocimiento básico de lenguaje de marcado AsciiDoc (consulte en AsciiDoc for Fedora)
Las herramientas
Manera rápida: botón «Editar»
-
Realiza los cambios a un solo archivo para reparaciones menores desde IU de web de la forja Git.
-
Acceso de escritura requerido para el repo ascendente.
-
Utilícelo como una excepción (sin proceso de revisión), en vez de una opción recomendada.
Manera fácil: IDE web de forja Git
-
Realiza los cambios a múltiples archivos directamente desde el IU web de la forja Git.
-
No necesita instalar nada en el equipo local o ejecute comandos de Git dentro del terminal.
-
Tirar Solicitudes para revisar proceso (Unir Solicitudes en GitLab)
-
No necesita permisos especiales o acceso con escritura para el proyecto original.
Las maneras típicas para contribuir
Uno puede distinguir varios tipos típicos de contribución a la documentación de Fedora, para lo cual las herramientas disponibles son adecuadas en diferentes maneras.
Hay muchas maneras para varios tipos de contribución. Por ejemplo, correcciones de tipado, añadir información breve o un enlace, actualizar un artículo, escribir un artículo nuevo.
Actualizar una página de documentación existente
Esta tarea involucra cambios menores. Por ejemplo, corrige tecleo, añade información breve o un enlace, o una corrección al texto. Este tipo es especialmente necesario cuando la documentación necesita ser actualizada para una versión de software nueva.
El botón de Editar Archivo es conveniente para este propósito.
Amplía un dominio de documentación existente
Esta tarea involucra añadir uno o más capítulo(s) o sección(es) con varios capítulos. Por ejemplo, añadir otra técnica de contenedor para la documentación de contenización.
El IDE Web es una herramienta conveniente para este propósito. Un entorno de escritura local es utilizable también, pero puede implicar demasiada sobrecarga si desea contribuir para tan solo un documento.
Es muy recomendable presentar el plan en uno de los canales de comunicación de Docs antes de comenzar. Puede recibir sugerencias y consejos sobre el contenido, pero también sobre la edición. Por ejemplo, sobre la estructura del archivo y las convenciones de nomenclatura.
Introducir un área de documentación nueva
Esta tarea implica un área temática extensa, como un software nuevo o una herramienta nueva de administración. Por ejemplo, la inclusión de varias secciones y capítulos y la creación de un repositorio nuevo independiente.
Para este tipo, es útil configurar un entorno de escritura local y vale la pena.
En cualquier caso, es necesaria una discusión previa con el equipo de Docs, si solo va a crear los pre-requisitos técnicos.
Want to help? Learn how to contribute to Fedora Docs ›