Cuando empecé a contribuir en Crucigramas, JRB me enseñó una lección muy valiosa: antes de implementar una función no trivial, o antes de hacer cambios extensos, primero hay que escribir un pequeño documento con el diseño de lo que vas a hacer. No tiene que ser nada formal; sólo una explicación del estado de cosas de donde vienes, el punto al que quieres llegar, y una pequeña explicación técnica de cómo llegar ahí si es adecuado. Entonces puedes discutir tu función nueva basándote en ese documento, en vez de lanzarse al hoyo de la madriguera de conejo que es la implementación.
Con el tiempo, esos documentos llegan a formar un resumen de alto nivel del proyecto que estás construyendo; una especie de historia del desarrollo sin todos los detalles irrelevantes que tiene el historial de commits.
Puedes ver ejemplos de estos documentos en el repositorio de Crosswords.
Empecé a hacer eso para las cosas que quería implementar en el programa de Crucigramas, y además en librsvg y tiempo después en at-spi2-core. Normalmente tengo archivos de texto, que no publico, con mis notas personales y planes de cosas que quiero implementar; el consejo de JRB me dio una excusa para hacerlos legibles y publicarlos.
Mientras estaba documentando la primera versión del CI de at-spi2-core, y al buscar referencias de cómo ponerle cobertura de código, me topé con la Documentación del Árbol de Código de Firefox y también con la Guía de Desarrollo de Rustc. Ambas tienen recorridos por secciones del código, documentación de los procedimientos de desarrollo — ese tipo de cosas. ¡Perfecto!
Me permito presentarles:
Ambos documentos se generan a partir de archivos de texto en sus respectivos repositorios. El HTML se publica desde el pipeline de CI, al mismo tiempo que la referencia del API. La idea es que estos documentos puedan mantenerse actualizados justo ahí mientras uno cambia el código, en vez de escribirse la primera vez y luego pudrirse poco a poco en un wiki.
Todo esto ya está dando frutos. Mi alumne de Outreachy para Diciembre 2022 pudo comenzar su desarrollo en librsvg sin siquiera tener que preguntarme cómo empezar, porque la guía de desarrollo tiene una sección de cómo hacerse de un ambiente de desarrollo. Su proyecto de Outreachy para monitorear el desempeño de librsvg también está descrito ahí. La guía de at-spi2-core me da un lugar para poner enlaces a datos oscuros, así como dónde mantener material de referencia for para los desarrolladores.
Detalles técnicos: ambos documentos están en reStructuredText, y se procesan con Sphinx, pues me pareció que tiene buen mantenimiento. También se podría usar algo como mdbook muy bien.
Todavía no tengo tanta práctica con reStructuredText y Sphinx como con Markdown, entonces si alguien tiene consejos de cómo hacer que se vean mejor los documentos (en particular, el índice al principio de la guía de at-spi2-core está terrible), agradecería sugerencias.
También tengo que modificar Crosswords para que esos documentos queden en un libro.
(¿Se acuerdan de la Hospitalidad del Código? Pues sí, exactamente eso.)