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:
- ScummVM
- Escritor 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) está publicada aquí: https://doxygen.scummvm.org/modules.html
Lamentablemente, carece en muchas áreas:
1) Prácticamente no tiene estructura, toda la información flota al mismo nivel.
2) Los elementos de C++ están documentados de manera inconsistente y algunos no están documentados. Este es un tema 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 idioma 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 de una futura guía de estilo de documentación para este proyecto.
5) Se puede 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 aplicación de esta temporada de Documentos incluye un borrador de comunicado de prensa que abrí en el proyecto para demostrar algunas de las posibles mejoras que propongo: https://github.com/scummvm/scummvm/pull/2361. Consulta la descripción para obtener algunos detalles sobre su contenido y para ver las diferencias.
Esto es, aproximadamente, lo que implica el comunicado de prensa:
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, por consiguiente, la usabilidad del documento. Es por eso que mi solicitud de extracción introduce grupos de doxígeno en todos los archivos de encabezado de la carpeta “common”. 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 permitir la compilación de esta documentación.
3) Un archivo 'links.doxyfile' a partir del cual todos los vínculos utilizados en todo el documento pueden tener una única fuente. Es un mecanismo útil cuando se trabaja con doxígeno.
4) Un CSS de doxígeno modificado Actualmente, esta información proviene 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.
Lo que el RR.PP. no abarca, pero definitivamente se debe trabajar sobre él, es el contenido en sí. 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 deberían quitarse de la documentación. Como no he trabajado antes en el proyecto, se necesitará la orientación de un mentor para lograrlo.
Por supuesto, la decisión de implementar algo desde el departamento de Relaciones Públicas depende de la conversación de 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 aplicación.
0
El único cambio que recomendarí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 doxygen (que ya está casi lista), y la actualización de la piel de Doxygen. Después de eso, estoy de acuerdo en que tiene más sentido revisar las diferentes áreas una por una con el mentor para identificar problemas y mejorar la documentación de doxígeno.
Veo que este es un proyecto de longitud estándar, pero estoy seguro de que habrá otras mejoras relacionadas con la documentación de la API que se pueden realizar después de que finalice el proyecto de GSoD. Por ejemplo, crear una guía de estilo para 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 ScummVM podría recurrir a un escritor técnico que se asegurará de que el documento de la API sea de buena calidad y usabilidad. También veo que hay otros proyectos de documentos en los que podría ayudarte, como crear una guía sobre cómo trabajar con complementos.