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:
- El lenguaje Julia
- Escritor 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 por mejorar en esta área y, sin duda, la finalización de este proyecto proporcionará beneficios inmediatos tanto a los programadores de Julia como a los colaboradores o encargados activos de SciML. Los paquetes repartidos por SciML ofrecen algunas herramientas muy útiles, pero siempre existe el riesgo de que pasen desapercibidas (especialmente para los principiantes) simplemente porque el usuario no pudo descubrir el paquete y aplicarlo al problema en cuestión.
Esto es bastante frustrante dado que el objetivo principal de los paquetes es llegar a un amplio público de programadores (principiantes y expertos por igual). Para evitar la situación descrita anteriormente, propongo revisar la "primera" de la documentación de SciML a fondo y crear una especie de centro que los usuarios puedan usar para navegar por paquetes relacionados y explorar 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 con respecto a los problemas estilísticos más básicos (como la ortografía, la puntuación, la gramática, etc.). Para garantizar la coherencia estilística, SciML debe tener una guía de estilo concreta (indispensable para realizar cambios retrospectivos y para referencia futura). Sería una pérdida de tiempo empezar desde cero. En cambio, debería basarse en las convenciones existentes de Julia y, además, incluir valores enteros nuevos para problemas específicos de SciML.
Una vez que la guía de estilo se haya completado, pienso revisar la documentación actual en la segunda fase del proyecto. Hará que la documentación parezca más profesional y estable. Ya creé varias solicitudes de extracción que ilustran mi enfoque para esta tarea. En esta fase, también deseo diseñar (e implementar) un sistema de citas eficiente. La primera tarea será actualizar la página de citas desactualizada.
La tercera fase, sin duda la más importante, consistirá en diseñar 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 del 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 exploraran minuciosamente los repositorios y la documentación respectivos. En lugar de enumerar todas las conexiones posibles entre los paquetes, preferiría centrarme en los 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 tutoriales en los que se debe señalar la conexión con otro paquete). Este enfoque garantiza que las listas "see también" serán informativas sin ser enumeraciones exhaustivas de combinaciones de paquetes.