Esta página contiene los detalles de un proyecto de redacción técnico aceptado para Google Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- Kolibri
- Redactor 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
Se puede abstraer
En este documento, se detalla la implementación de los lineamientos de estilo y la administración del flujo de trabajo en la información documentada de Learning Equality para el proyecto Kolibri Ecosystem.
Descripción general
Mi propuesta consta de cuatro fases. En la primera fase, completaré la Guía de estilo de documentación de LE con pautas de accesibilidad, escritura y recomendaciones de formato siguiendo los conceptos y los lineamientos de estilo de LE en el desarrollo de software. En la segunda fase, realizaré una auditoría de calidad de los documentos de ReadTheDocs y GoogleDocs. 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 verificación ayudarán a registrar los hallazgos y aplicar cambios a la documentación. En la tercera fase, trabajaré en la estructura, el aspecto y el estilo de las plantillas de los documentos de ReadTheDocs y GoogleDocs. Crearé una plantilla y un repositorio de imágenes en Google Drive en el que identificaré cada categoría de plantillas de los principales tipos de documentos para reutilizar en las próximas implementaciones. Complementaré esta tarea creando plantillas para enviar problemas de documentos a fin de identificarlos con facilidad en las revisiones de las solicitudes de extracción. Por último, crearé una Guía para colaboradores en la que se agruparán recursos útiles para cada grupo de colaboradores con el objetivo de 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 que utilizan los documentos de Kolibri y ayudar a los miembros del equipo y colaboradores a producir una mejor documentación y una colaboración activa en la comunidad. Esta implementación se aplica a ReadTheDocs y a los subconjuntos de documentos de Documentos de Google en el ecosistema de Kolibri.
Público
El público principal de implementadores, administradores y usuarios finales son los consumidores más críticos de la documentación de Kolibri. Un público secundario de miembros del equipo y colaboradores para su producción y uso de la documentación de Kolibri.
Objetivos
La guía de estilo y el sistema de flujo de trabajo de Kolibri Ecosystem Documentation espera que los usuarios: Compilar documentación con un lenguaje accesible y un diseño coherente. Preservar el mantenimiento de las prácticas de calidad luego de la documentación. Facilita el acceso a la información entre los canales de documentación. Refuerza las iniciativas de colaboración en la comunidad de código abierto de Kolibri.
Fuentes de información
Mis fuentes de información son Kolibri, Kolibri Studio, documentos de Kolibri Development RTD y Kolibri Toolkits de Google Drive.
El maravilloso Radina Matic fue de gran ayuda para brindar actividades de calentamiento y actividades específicas para proyectos. Su aporte sobre lo que la organización conceptualiza como "Lineamientos" y "Guías" y con respecto a la existencia de una Guía para colaboradores me ayudó a organizar mis ideas y redactar conclusiones.
Software
Voy a 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, usaré Formularios de Google para llevar a cabo y evaluar documentos. Una hoja de cálculo almacenará las respuestas del formulario para controlar el documento. Refactorizaré los documentos de RTD con GitHub. Trabajé con Git, Gitkraken, GitHub y Gitlab. Tengo conocimientos prácticos sobre Markdown y algunos recursos Reestructurados. Quiero contribuir con las correcciones de documentación para seguir aprendiendo la sintaxis. Usaré Sharex para imágenes y GIFs. Me encanta esta herramienta porque se renderiza en diferentes formatos de salida. Usaré diagramas para la diagramación y la edición de imágenes. El software de diagramas se integra perfectamente en 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, tipografías, incoherencias en el diseño, la tipografía y el uso de imágenes, además de 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, no un tema. Esta información es lo suficientemente crítica como para que los usuarios finales puedan acceder a ella desde el índice. Como segunda alternativa, pueden utilizar la barra de búsqueda y el árbol del índice para expandir otros temas y ubicar artículos de solución de problemas.
Para acceder a la sección “Solución de problemas”, debes buscarla o expandir “Administrar Kolibri” para darte cuenta de que la solución de problemas existe como parte de la documentación. Guía vs. lineamientos Para esta propuesta de proyecto, analicé dos documentos: Guía de estilo para la documentación del usuario de LE Kolibri y Pautas de traducción de LE Kolibri. En la guía de LE Kolibri, hice recomendaciones y comentarios a partir del esquema de tema y el plan de documentación que propuse, además de otras cuestiones que deben mejorar en la Guía. Para los Lineamientos de traducción de inglés, cambié el formato y el estilo en función de mis recomendaciones y convenciones existentes en la Guía de estilo. Lo que más me llamó la atención durante el análisis fue el concepto erróneo que existe entre los documentos categorizados como Guía y Lineamientos.
Resultados
Realicé una comprobación de calidad en la guía de traducción de LE, además de sugerencias y comentarios, con un formulario preliminar que explico con más detalle en la tarea de auditoría de QA. Estos son algunos de los comentarios finales que se obtuvieron de la evaluación: Vínculos rotos en el sitio web .js de la sintaxis de ICU El formato que se usó para crear estos lineamientos es incorrecto. El documento es una guía, no una guía. La tipografía no es uniforme. Uso incorrecto de encabezados y títulos, Uso inadecuado del lenguaje y de las contracciones Uso inadecuado de textos alternativos Sobre afirmaciones o instrucciones repetidas.
Los hallazgos de ambos documentos forman parte de los Ítems de esta propuesta.
Tareas específicas del proyecto
- Recomendaciones de la Guía de estilo de la documentación del usuario de LE (comentarios)
- Lineamientos de traducción de LE con nuevos estilos y formatos.
- Esquema del tema
- Cronograma del proyecto
- Tareas de documentación