En esta página, se incluyen 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:
- CERN-HSF
- Redactor técnico:
- SabitaR
- Nombre del proyecto:
- Reestructuración y optimización de la documentación de Allpix Squared
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
RESUMEN Elegí el proyecto Allpix Squared del CERN-HSF por dos razones principales:
Desarrollo de habilidades: La documentación existente de este proyecto es integral y, además, integra varios formatos de contenido. Auditar y reestructurar este amplio paquete de documentos me ayudará a perfeccionar mi arquitectura de la información y mis habilidades de escritura. Además, el dominio del proyecto (física de partículas) es nuevo para mí. Me desafía a perfeccionar mis habilidades de interacción con los desarrolladores. Creo que los redactores técnicos pueden procesar las entradas de los desarrolladores y presentar contenido útil para cualquier nivel de usuario, SI hacemos la investigación de antecedentes necesaria y hacemos las preguntas correctas. Este proyecto me permitirá probar esta teoría.
Conocimientos técnicos: Este proyecto requiere Hugo, una herramienta que se encuentra en la parte superior de mi lista de tareas pendientes. Espero aprender el flujo de trabajo de LaTeX-Markdown-Hugo-GitLab-CI.
Durante la fase de exploración del escritor técnico, interactué brevemente con los mentores del proyecto y me familiaricé con la estructura existente del paquete de documentos. También creé un sitio web de demostración (https://ap2-demo.netlify.app/) para probar si puedo configurar Hugo y Docsy correctamente en mi máquina con Windows. Pude implementar el sitio web en Netlify, pero no en Gitlab Pages. Para que este proyecto mantenga su flujo de trabajo de implementación actual, encontraré una forma de implementar el tema Docsy de Hugo en Gitlab Pages.
RESULTADOS ESPERADOS DEL PROYECTO - Un sitio web del proyecto optimizado que integra documentación, referencia de código, tutoriales y noticias. - Un manual de usuario reestructurado y revisado que separa el contenido destinado a los usuarios y a los desarrolladores, y que incluye información que faltaba anteriormente. - Un flujo de trabajo de tutoriales a partir de ejemplos disponibles de documentación de instrucciones, preguntas frecuentes y problemas habituales.
HERRAMIENTAS DE PROYECTO La documentación actual de Allpix Squared usa LaTeX, Doxygen, pandoc y Hugo, además de GitLab y Gitlab CI. Los mentores del proyecto y yo conversamos sobre la posibilidad de transferir contenido de LaTeX a Markdown con complementos de MathJax. Si tengo éxito, el flujo de trabajo del documento involucrará a Hugo, Markdown, Doxygen, Git y GitLab CI. Para mantener los instructivos en el mismo sitio web o plataforma, usaré Hugo y Markdown. Me gustaría saber si es posible usar Codelabs como herramienta (ClaaT) para los instructivos. En julio, espero poner a prueba el flujo de trabajo de ClaaT-Hugo y analizarlo con los mentores, si resultaran seleccionados.
DURACIÓN del PROYECTO Solicito completar el proyecto Allpix Squared dentro del período estándar de tres meses (del 14 de septiembre de 2020 al 30 de noviembre de 2020), durante el cual dedicaré aproximadamente 15 horas por semana a él. Estas horas incluirán reuniones con el mentor y correos electrónicos relacionados, según sea necesario. También cumpliré con los cronogramas de GSoD para la vinculación con la comunidad y la finalización del proyecto.
TAREAS DEL PROYECTO Esta es la forma en que pienso implementar las actualizaciones que propongo en el paquete existente de documentos de Allpix Squared: 1. Investigar, debatir y explorar opciones (del 17 de agosto al 13 de septiembre de 2020): - Comprender los requisitos del proyecto - Instalar el software Allpix Squared para identificar información faltante, si la hay, en los documentos actuales. - Solicita las credenciales necesarias. - Crear flujos de trabajo de usuarios para diferentes usuarios de Allpix Squared - Clasificar el contenido según el rol del usuario - Comprobar las implicaciones de convertir archivos LaTeX a Markdown - Consolidar repositorios de código fuente o comprender cómo trabajar con varios repositorios de Git - Contenido adicional: Prueba CLaaT como opción para instructivos - Contenido adicional: Crea una guía de estilo rápida/referencia de códigos cortos para ayudar a los colaboradores a mantener documentos de cronograma :
Reestructurar, revisar y mejorar el contenido (del 14 de septiembre al 19 de octubre de 2020): Dos tareas por semana, de aproximadamente 5 a 7 horas por tarea. Este cronograma incluye una semana de reserva para manejar retrasos o problemas inesperados.
- Revisa el contenido existente y las clasificaciones de los usuarios teniendo en cuenta los flujos de trabajo de los usuarios
- Describir y probar el flujo de trabajo de contenido reestructurado para diferentes usuarios
- Obtener y mejorar el contenido faltante
- Cómo convertir archivos LaTeX a Markdown
- Finaliza la guía del usuario y el índice de la guía para desarrolladores
- Genera archivos PDF de las guías para usuarios y desarrolladores
- Bono: Estructura el contenido de los instructivos a partir de ejemplos y problemas
- Bonificación: Configura un flujo de trabajo de instructivo para ejemplos de instructivos Cronograma: 5 semanas (fase de desarrollo de documentos)
Crear el sitio web (del 19 de octubre al 30 de noviembre de 2020): 1 o 2 tareas por semana, de 5 a 7 horas por tarea. Este cronograma incluye una semana de reserva para solucionar problemas y definir mejor el resultado final.
- Comprende y prueba el flujo de trabajo de publicación
- Crea la estructura de un sitio web con Hugo y Docsy
- Probar cómo mantener la implementación automática y el flujo de trabajo actuales con Documentosy
- Extrae contenido de Doxygen
- Desarrolla manuales de usuario, instructivos y guías para desarrolladores a partir del contenido de LaTex o Markdown
- Finalizar el aspecto del sitio web del proyecto (logotipo, colores, plantilla, diseño, vínculos, usabilidad y CI/CD de Gitlab) Cronograma: 6 semanas (fase de desarrollo de documentos)