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:
- CERN‐HSF
- Escritor 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
DESCRIPCIÓN GENERAL Elegí el proyecto Allpix Squared de CERN-HSF por dos razones principales:
Desarrollo de habilidades: La documentación existente de este proyecto es exhaustiva y permite integrar varios formatos de contenido. Auditar y reestructurar este extenso paquete de documentos me ayudará a pulir mi arquitectura de la información y mis habilidades de redacción. 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 escritores técnicos pueden procesar los aportes de los desarrolladores y presentar contenido útil a cualquier nivel de usuarios, SI hacemos la investigación previa requerida y formulamos las preguntas correctas. ¡Este proyecto me permitirá probar esta teoría!
Conocimiento técnico: Para este proyecto, se necesita Hugo, una herramienta que aparece en la parte superior de mi lista de cosas para aprender. Espero con ansias aprender el flujo de trabajo de LaTeX-Markdown-Hugo-GitLab-CI.
Durante la fase de exploración técnica del escritor, 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 Windows. Pude implementar el sitio web en Netlify, pero no en páginas de GitLab. Para que este proyecto mantenga su flujo de trabajo de implementación actual, encontraré una forma de implementar el tema de Hugo Docsy en las páginas de GitLab.
RESULTADOS ESPERADOS DE LOS PROYECTOS - Un sitio web optimizado para proyectos que integra documentación, referencias de código, tutoriales y noticias. - Un manual del usuario reestructurado y revisado que separa el contenido destinado a los usuarios y los desarrolladores y que incluye información que faltaba anteriormente - Un flujo de trabajo de tutoriales a partir de ejemplos disponibles de documentación práctica, preguntas frecuentes y problemas habituales.
HERRAMIENTAS DE PROYECTO En la documentación actual de Allpix Squared, se usan LaTeX, Doxygen, pandoc y Hugo, además de GitLab y GitLab CI. Con los mentores del proyecto y yo conversamos sobre la posibilidad de trasladar contenido de LaTeX a Markdown con complementos de MathJax. Si tengo éxito, el flujo de trabajo de documentos incluirá Hugo, Markdown, Doxygen, git y GitLab CI. Para tener los instructivos dentro del mismo sitio web o plataforma, usaré Hugo y Markdown. Me interesa saber la viabilidad de usar codelabs como herramienta (ClaaT) para los instructivos. En julio, espero probar el flujo de trabajo ClaaT-Hugo y analizarlo con los mentores si son seleccionados.
DURACIÓN DEL PROYECTO Solicito completar el proyecto de 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 le dedicaré aproximadamente 15 horas por semana. Estas horas incluirán reuniones con mentores y correos electrónicos relacionados, según sea necesario. También me respetaré con los cronogramas de GSoD para la vinculación con la comunidad y la finalización del proyecto.
TAREAS DE PROYECTOS Así es como pienso implementar las actualizaciones que propongo para el paquete de documentos existente de Allpix Squared: 1. Investiga, analiza y explora opciones (del 17 de agosto al 13 de septiembre de 2020): - Comprende los requisitos del proyecto. - Instala el software Allpix Squared para identificar la información faltante, si la hay, en los documentos actuales. - Solicita las credenciales necesarias. - Crear flujos de trabajo de usuario para diferentes usuarios de Allpix Squared - Clasificar contenido según el rol del usuario - Comprobar las implicaciones de convertir archivos LaTeX a Markdown - Consolidar repositorios de origen o comprender cómo trabajar con varios repositorios de Git - Bonificación: Prueba CLaaT como opción para los instructivos - Bonificación: Crea una guía de estilo rápida/referencia de códigos cortos para ayudar a mantener documentos.
Reestructura, revisa y mejora 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 un margen de semana para gestionar retrasos o problemas inesperados.
- Revisa el contenido existente y las clasificaciones de los usuarios teniendo en cuenta los flujos de trabajo de los usuarios
- Define y prueba el flujo de trabajo de contenido reestructurado para diferentes usuarios
- Cómo buscar y mejorar el contenido que falta
- Convierte archivos LaTeX a Markdown
- Finaliza la guía del usuario y el índice de la guía para desarrolladores.
- Generar archivos PDF de las guías del usuario y del desarrollador
- Bonificación: Estructura el contenido para instructivos a partir de ejemplos y problemas
- Contenido adicional: Configura un flujo de trabajo de instructivos para ver ejemplos prácticos Cronograma: 5 semanas (fase de desarrollo del documento)
Creación del sitio web (del 19 de octubre al 30 de noviembre de 2020): De 1 a 2 tareas por semana, de 5 a 7 horas por tarea aproximadamente. En este cronograma se incluye una semana de reserva para solucionar los problemas y ajustar el resultado final.
- Comprende y prueba el flujo de trabajo de publicación
- Crear la estructura de un sitio web con Hugo y Docsy
- Prueba cómo mantener el flujo de trabajo y la implementación automática actual con Documentosy
- Extrae contenido de Doxygen
- Desarrolla un manual del usuario, una guía para desarrolladores y tutoriales a partir de contenido de LaTex o Markdown.
- Finaliza 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 del documento)