Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
Resumen del proyecto
- Organización de código abierto:
- Kolibri
- Escritor técnico:
- StephDix
- Nombre del proyecto:
- Estilo de documentación del ecosistema de Kolibri y convenciones de flujos de trabajo
- 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 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, escritura y recomendaciones de formato según los conceptos de LE y las pautas de estilo 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 y el aspecto de las plantillas de los documentos de ReadTheDocs y GoogleDocs. Crearé una plantilla y un repositorio de imágenes en Google Drive. Para ello, identificaré cada categoría de plantilla con los principales tipos de documentos para reutilizarlos 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 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 fin de mejorar su experiencia al acceder 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 Google Docs en el ecosistema 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 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 a los usuarios lo siguiente: Crear documentación resumida con lenguaje accesible y un diseño coherente. Preservar el mantenimiento de las prácticas de calidad tras la documentación. Mantener la facilidad de 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 fueron Kolibri, Kolibri Studio, los documentos de Kolibri Development RTD y Kolibri Toolkit de Google Drive.
La maravillosa Radina Matic fue de gran ayuda para brindar actividades de calentamiento y actividades específicas de proyectos. Su opinión 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 elaborar 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, usaré Formularios de Google para conducir y evaluar documentos. Una hoja de cálculo almacenará las respuestas del formulario para controlar los documentos. Refactorizaré los documentos de RTD con GitHub. Trabajé con Git, Gitkraken, GitHub y Gitlab. Tengo conocimientos prácticos sobre Markdown y algunos recursos de ReestructuraText. Planeo 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 procesa 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 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, tipográficos, incoherencias en el diseño, la tipografía y el uso de la imagen, así como 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 resulta lo suficientemente crítica 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 ubicar artículos de solución de problemas.
Para acceder a la sección “Troubleshooting”, deben buscarla o expandir la sección “Manage Kolibri” para saber que la solución de problemas existe como parte de la documentación. Guía vs. lineamientos Para esta propuesta de proyecto, analizó dos documentos: Guía de estilo para la documentación del usuario de LE Kolibri y Pautas para la 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 propuestos, además de otras cosas que deben mejorar en la guía. Para las Pautas de traducción de LE, 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 las sugerencias y los comentarios con un formulario preliminar que explico con más detalle en la tarea de auditoría de QA. Estos son algunos comentarios finales que se obtuvieron de la evaluación: Vínculos rotos del sitio web .js de ICU Syntax 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 coincide. Uso incorrecto de encabezados y títulos Uso inadecuado de lenguaje y uso inadecuado de contracciones Uso inadecuado de textos alternativos Sobre afirmaciones o instrucciones repetidas
Los resultados de ambos documentos forman parte de los Ítems de esta propuesta.
Tareas específicas del proyecto
- Recomendaciones de la Guía de estilo para la documentación del usuario de bajo consumo (comentarios)
- Lineamientos de traducción de LE con nuevos estilos y formatos.
- Resumen del tema
- Cronograma del proyecto
- Tareas de documentación