Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- Kolibri
- Escritor técnico:
- StephDix
- Nombre del proyecto:
- Convenciones de estilo y flujos de trabajo de la documentación del ecosistema de Kolibri
- Duración del proyecto:
- Larga duración (5 meses)
Project description
Resumen
En este documento, se detalla la implementación de los lineamientos de estilo y la administración de flujos de trabajo en la información documentada de Learning Equality para el proyecto del ecosistema de Kolibri.
Descripción general
Mi propuesta consta de cuatro fases. En la primera fase, completaré la Guía de estilo de la documentación de LE con pautas de accesibilidad, redacción y recomendaciones de formato según los conceptos y las pautas de estilo de LE para el desarrollo de software. En la segunda fase, realizaré una auditoría de calidad en los documentos de ReadTheDocs y Documentos de Google. El plan de auditoría integra el uso de listas de verificación para evaluar el cumplimiento de las pautas de estilo. Estas listas de tareas te ayudarán a registrar los hallazgos y aplicar cambios a la documentación. En la tercera fase, trabajaré en la estructura, el aspecto y la sensación de las plantillas de los documentos de ReadTheDocs y Documentos de Google. Crearé una plantilla y un repositorio de imágenes en Google Drive en el que identificaré cada categoría de plantilla de los principales tipos de documentos para reutilizarlos en las próximas implementaciones. Complementaré esta tarea creando plantillas para enviar problemas de documentos para una fácil identificación en las revisiones de solicitudes de extracción. Por último, crearé una Guía para colaboradores que agrupará recursos útiles para cada grupo de colaboradores para mejorar su experiencia de acceso a la información.
Propósito y alcance
El objetivo de este plan de implementación es mejorar la experiencia de los usuarios finales con los documentos de Kolibri y ayudar a los miembros del equipo y a los colaboradores a producir una mejor documentación y una colaboración activa en la comunidad. Esta implementación se aplica a ReadTheDocs y a subconjuntos de documentos de Documentos de Google en el ecosistema de Kolibri.
Público
Un público principal de implementadores, administradores y usuarios finales que son los consumidores más importantes de la documentación de Kolibri. Un público secundario de miembros del equipo y colaboradores para la producción y el uso de la documentación de Kolibri.
Objetivos
El sistema de guía de estilo y flujo de trabajo para la documentación del ecosistema de Kolibri espera que los usuarios hagan lo siguiente: Crea documentación fácil de entender con un lenguaje accesible y un diseño coherente. Preservar el mantenimiento de las prácticas de calidad a partir de la documentación. Mantener la facilidad de acceso a la información entre los canales de documentación. Reforzar las iniciativas de colaboración en la comunidad de código abierto de Kolibri
Fuentes de información
Mis fuentes de información fueron Kolibri, Kolibri Studio, documentos de RTD de Kolibri Development y Kolibri Toolkits de Google Drive.
La maravillosa Radina Matic fue de gran ayuda para proporcionar actividades de preparación y actividades específicas del proyecto. Sus aportes sobre lo que la organización conceptualiza como ""Lineamientos"" y ""Guías"", y sobre la existencia de una Guía para colaboradores, me ayudaron a organizar mis ideas y a redactar conclusiones.
Software
Desarrollaré el borrador de la guía de estilo en Documentos de Google. Esta plataforma de documentos es perfecta para iterar mientras está lista para su publicación. Para la auditoría de QA, utilizaré Formularios de Google para llevar a cabo y evaluar documentos. Una hoja de cálculo almacenará las respuestas del formulario para el control de documentos. Refactorizaré los documentos de RTD con GitHub. Trabajé con Git, Gitkraken, GitHub y Gitlab. Tengo conocimientos prácticos de Markdown y un poco de RestructuredText. Planeo contribuir con correcciones de documentación para seguir aprendiendo la sintaxis. Usaré Sharex para las imágenes y los GIFs. Me encanta esta herramienta porque se renderiza en diferentes formatos de salida. Usaré diagramas para la creación de diagramas y la edición de imágenes. El software de diagramas se integra perfectamente con Documentos de Google, Google Drive y LibreOffice. Estado de la documentación En la fase de exploración, revisé la mayor parte de la documentación de Kolibri. Encontré errores gramaticales, tipográficos, inconsistencias en el diseño, la tipografía, el uso de imágenes y, además, rutas de documentación confusas en la mayor parte de la documentación del proyecto. Por ejemplo, en la Guía del usuario de Kolibri, la sección de solución de problemas es un subtema y no un tema. Esta información es lo suficientemente importante como para que los usuarios finales puedan acceder a ella desde el índice. Como segunda alternativa, pueden usar la barra de búsqueda y el árbol del índice para expandir otros temas y encontrar artículos de solución de problemas.
Para acceder a la sección "Solución de problemas", tienes que buscarla o expandir "Administrar Kolibri" para darse cuenta de que la solución de problemas existe como parte de la documentación. Guías y lineamientos Para esta propuesta de proyecto, analicé dos documentos: la guía de estilo de la documentación para el usuario de LE Kolibri y los lineamientos de traducción de LE. En la guía de LE Kolibri, hice recomendaciones y comentarios sobre mi plan de documentación y el esquema de temas propuesto, además de otros aspectos que deben mejorarse en la guía. En el caso de los Lineamientos de Traducción de LE, cambié el formato y el estilo en función de mis recomendaciones y las convenciones existentes en la Guía de Estilo. Lo que más me llamó la atención durante el análisis fue el malentendido que existe entre los documentos categorizados como Guía y Lineamientos.
Resultados
Hice una comprobación de calidad en la guía de traducción de LE, además de las sugerencias y comentarios con un formulario preliminar que explico con más detalle en la tarea de auditoría de QA. Estos son algunos comentarios finales obtenidos de la evaluación: Vínculos rotos para el sitio web ICU Syntax .js El formato que se usó para crear estos lineamientos es incorrecto. El documento es una guía, no lineamientos. La tipografía no es coherente. Uso incorrecto de encabezados y títulos, uso inadecuado del lenguaje y uso incorrecto de contracciones. Uso incorrecto de textos alternativos Sobre instrucciones o sentencias repetidas.
Las conclusiones de ambos documentos forman parte de los entregables de esta propuesta.
Tareas específicas del proyecto
- Recomendaciones de la Guía de estilo de la documentación para el usuario de LE (comentarios)
- Lineamientos de traducción de LE con nuevos estilos y formato.
- Esquema del tema
- Cronograma del proyecto
- Tareas de documentación