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:
- 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 (código fuente) de ScummVM está publicada aquí: https://doxygen.scummvm.org/modules.html
Lamentablemente, faltan en muchas áreas:
1) Prácticamente no tiene una estructura, toda la información flota en el mismo nivel.
2) Los elementos de C++ están documentados de manera inconsistente y algunos de ellos no están documentados en absoluto. Esto es algo que la organización menciona como uno de los problemas principales.
3) Aún se muestra contenido obsoleto y obsoleto en el resultado.
4) El lenguaje y el uso del etiquetado de doxígeno deben ser más coherentes. Se necesita un conjunto de reglas para esto, algo que podría ser la base para una futura guía de estilo de documentación para este proyecto.
5) El CSS de doxygen que se usa en esta página podría mejorarse para que sea más similar al sitio web de ScummVM: https://www.scummvm.org.
Todos estos problemas pueden abordarse durante el proyecto Temporada de Documentos.
Esta aplicación de la Temporada de Documentos viene acompañada de un borrador de RR.PP. que abrí en el proyecto para demostrar algunas mejoras potenciales que propongo: https://github.com/scummvm/scummvm/pull/2361 Consulta la descripción allí para obtener algunos detalles sobre su contenido y ver la diferencia.
A grandes rasgos, esto es lo que implica:
1) Creo que lo que es 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 estructurada de API mejoraría la legibilidad, la facilidad de búsqueda y, por lo tanto, la usabilidad del documento. Es por eso que mi RR.PP. introduce grupos de doxígenos en todos los archivos de encabezado de la carpeta 'común'. Con esta nueva estructura, si alguien quiere encontrar documentos para la API relacionada con el SO (por ejemplo), puede encontrarlos fácilmente en la navegación.
2) Se establece un nuevo archivo de configuración de doxygen para habilitar la compilación de esta documentación.
3) Un archivo 'links.doxyfile' a partir del cual todos los vínculos utilizados en el docset pueden tener una única fuente. Un mecanismo útil para trabajar con doxígeno
4) Un CSS de doxígeno modificado Actualmente, esto se toma de otro proyecto de código abierto y es solo un punto de partida. Idealmente, la apariencia de la página de doxígeno debería ser más o menos coherente con la página web de ScummVM.
El RR.PP. 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 desactualizadas del código que deben quitarse de la documentación. Como no he trabajado antes en el proyecto, se necesita la orientación de un mentor para lograrlo.
Por supuesto, si implementamos algo desde las relaciones públicas depende de la conversación con la organización. Mi idea era que las acciones hablaran más fuerte que las palabras, por lo que decidí mostrar lo que podía hacer en lugar de solo describirlo en la aplicación.
La organización proporcionó el siguiente cronograma general 0
El único cambio que proponería es comenzar trabajando 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 doxígeno (lo que ya está hecho) y la actualización de la piel de Doxygen. Después de eso, estoy de acuerdo en que tiene más sentido repasar las diferentes áreas una por una con el mentor para identificar los problemas y mejorar la documentación de doxígeno.
Veo que este es un proyecto de longitud estándar, pero estoy seguro de que hay otras mejoras relacionadas con la documentación de las APIs que pueden realizarse después de que finalice el proyecto de GSoD. Por ejemplo, crear una guía de estilo para la documentación y agregarla a la wiki, de modo que los colaboradores sepan cómo deben documentar el código que están agregando.
Con gusto te ayudaré con tareas como esta después de que termine GSoD. Estoy seguro de que a ScummVM le serviría un escritor técnico que se asegurará 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 puedo ayudarte, como la creación de una guía sobre cómo trabajar con complementos.