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:
- El idioma Julia
- Redactor técnico:
- mkg33
- Nombre del proyecto:
- La documentación unificada de Scientific Machine Learning
- Duración del proyecto:
- Larga duración (5 meses)
Project description
Me gustaría trabajar en la unificación de la organización de SciML porque hay mucho margen de mejora en esta área y la finalización de este proyecto sin duda proporcionará beneficios inmediatos tanto a los programadores de Julia como a los colaboradores o mantenedores activos de SciML. Los paquetes dispersos en SciML ofrecen algunas herramientas realmente útiles, pero siempre existe el peligro de que pasen desapercibidos (especialmente para los recién llegados) simplemente porque el usuario no pudo descubrir el paquete y aplicarlo al problema en cuestión.
Esto es bastante frustrante, ya que el objetivo principal de los paquetes es llegar a un público amplio de programadores (tanto principiantes como expertos). Para evitar la situación descrita anteriormente, propongo revisar en detalle la "página principal" de la documentación de SciML y crear una especie de centro que los usuarios puedan usar para explorar paquetes relacionados y el ecosistema en crecimiento. También podría servir como un punto de referencia valioso para los usuarios más experimentados y permitirles trabajar de manera más eficiente.
En primer lugar, la documentación existente de todos los paquetes individuales debe revisarse en relación con los problemas estilísticos más básicos (como la ortografía, la puntuación, la gramática, etcétera). Para garantizar la coherencia estilística, SciML debe tener una guía de estilo concreta (indispensable para realizar cambios retrospectivos y como referencia en el futuro). Sería una pérdida de tiempo empezar de cero. En cambio, debe basarse en las convenciones existentes de Julia e incluir completos nuevos para los problemas específicos de SciML.
Una vez que se complete la guía de estilo, mi intención es revisar la documentación actual en la segunda fase del proyecto. Hará que la documentación se vea más profesional y estable. Ya creé varias solicitudes de extracción que ilustran mi enfoque para esta tarea. En esta fase, también tengo la intención de idear (e implementar) un sistema de citas eficiente. La primera tarea será actualizar la página de citas desactualizada.
La tercera fase, posiblemente la más importante, implicará el diseño de la hoja de ruta de SciML, que enfatizará la interacción entre los paquetes dispersos. Cuanto más fuerte sea la cohesión entre dos paquetes (con respecto al problema o al código en sí), más cerca deberían aparecer en la lista "Ver también". Propongo crear dos claves de recomendación: una para la similitud de código y otra para la similitud de problemas. De esta manera, los usuarios podrían identificar otros paquetes potencialmente útiles mucho más rápido que si tuvieran que navegar laboriosamente por los repositorios y la documentación correspondientes. En lugar de enumerar todas las conexiones posibles entre los paquetes, prefiero enfocarme en las más grandes y tratar de presentar sus vínculos con paquetes más pequeños (este método también se extenderá a la actualización de instructivos en los que se debe señalar la conexión con otro paquete). Este enfoque garantiza que las listas de “ver también” sean informativas sin ser enumeraciones exhaustivas de combinaciones de paquetes.