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:
- ScummVM
- Redactor técnico:
- b-gent
- Nombre del proyecto:
- Mejora la documentación del código fuente con Doxygen
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
La documentación actual de la API de ScummVM (código fuente) se publica aquí: https://doxygen.scummvm.org/modules.html
Desafortunadamente, carece de muchas áreas:
1) Prácticamente no tiene una estructura, toda la información flota en el mismo nivel.
2) Los elementos de C++ se documentan de forma incoherente y algunos no están documentados en absoluto. Esto es algo que la organización menciona como uno de los problemas principales.
3) El contenido desactualizado y obsoleto aún se muestra en el resultado.
4) El lenguaje y el uso de los etiquetados de doxygen deben ser más coherentes. Se necesita un conjunto de reglas para esto, algo que podría ser la base de un futuro manual de estilo de documentación para este proyecto.
5) Se podría mejorar el CSS de doxygen que se usa en esta página para que sea más similar al sitio web de ScummVM: https://www.scummvm.org
Todos estos problemas se pueden abordar durante el proyecto de la Temporada de Documentos.
Esta solicitud de la Temporada de documentos se acompaña de un borrador de PR que abrí en el proyecto para demostrar algunas posibles mejoras que propongo: https://github.com/scummvm/scummvm/pull/2361 Consulta la descripción para obtener algunos detalles sobre lo que contiene y ver la diferencia.
Esto es, en términos generales, lo que implica la RP:
1) Creo que lo más confuso en este momento para los posibles colaboradores nuevos y, en general, para todos los que ven el documento actual de la API, es la falta de estructura. La introducción de documentación de API estructurada mejoraría la legibilidad, la facilidad de búsqueda y, en consecuencia, la usabilidad del documento. Es por eso que mi PR presenta grupos de doxygen a todos los archivos de encabezado de la carpeta "common". Con esta nueva estructura, si alguien quiere encontrar documentos para una API relacionada con el SO (por ejemplo), puede encontrarlos fácilmente en la navegación.
2) Se configura un nuevo archivo de configuración de doxygen para permitir la compilación de esta documentación.
3) Un archivo "links.doxyfile" desde el que todos los vínculos utilizados en el conjunto de documentos pueden tener un solo origen. Es un mecanismo útil cuando se trabaja con doxygen.
4) Un CSS de doxygen modificado Actualmente, se tomó de otro proyecto de código abierto y es solo un punto de partida. Idealmente, el aspecto de la página de doxygen debe ser más o menos coherente con la página web de ScummVM.
El departamento de Relaciones Públicas no abarca el contenido en sí, pero sí hay que trabajar en él. Con eso me refiero a identificar las partes esenciales del código que no están documentadas, las que no están lo suficientemente documentadas o las partes de código desactualizadas que deberían quitarse de la documentación. Como no he trabajado en el proyecto antes, necesitaré la orientación de un mentor para lograrlo.
Por supuesto, la implementación de algo, desde las relaciones públicas, depende de la conversación con la organización. Mi idea era que las acciones hablan más que las palabras, así que decidí mostrar lo que puedo hacer en lugar de solo describirlo en la solicitud.
La organización proporcionó el siguiente cronograma aproximado para este proyecto: Semana Tarea principal Semana 0 (antes del 14/9) Discusión y revisión de la propuesta Semana 1 (14/9) Configuración de la compilación de Doxygen Semana 2 (21/9) Actualización del diseño de Doxygen (prioridad baja) Semana 3 (28/9) Código común: OSystem, FS, estructuras de datos, cadenas, etcétera. Semana 4 (5/10) Código común: Continuación Semana 5 (12/10) Motores: código común y motor de muestra Semana 6 (19/10) Gráficos Semana 7 (26/10) Audio Semana 8 (2/11) Video, imágenes Semana 9 (9/11) Backends: plataformas, gráficos y eventos Semana 10 (23/11) Backends: Continuación Semana 11 (30/11) Resumen y envío del proyecto
El único cambio que te propongo es comenzar por trabajar en la estructura, como ya se mencionó. Esto se puede hacer en las semanas 1 y 2, junto con la configuración de compilación de doxygen (que ya está casi completa) y la actualización de la máscara de Doxygen. Después de eso, estoy de acuerdo en que lo más conveniente es revisar las diferentes áreas una por una con el mentor para identificar los problemas y mejorar la documentación de doxygen.
Veo que este es un proyecto de duración estándar, pero estoy seguro de que hay otras mejoras relacionadas con la documentación de la API que se pueden hacer después de que finalice el proyecto de GSoD. Por ejemplo, crear una guía de estilo de documentación y agregarla a la wiki, para que los colaboradores sepan cómo deben documentar el código que están agregando.
Con gusto te ayudaré con tareas como esta cuando finalice el GSoD. Estoy seguro de que ScummVM podría recurrir a un escritor técnico que se asegure de que su documento de API sea de buena calidad y usabilidad. También veo que hay otros proyectos de documentos futuros con los que podría ayudarte, como crear una guía sobre cómo trabajar con complementos.