En lo que a mí respecta, cuanto más cerca guarde la documentación del código, es más probable que se mantenga actualizado y más útil sea.
Es por eso que trato de mantener toda la documentación en el mismo repositorio que el código, incluso los manuales de usuario, y trato de mantenerla en un formato de texto sin formato que pueda ser fácilmente administrado por un sistema de control de revisiones.
Documentación en código
Parece que ya lo tiene cubierto, pero es importante recordar que el uso de las funciones de documentación en el entorno de desarrollo elegido ( pydoc para python, javadoc en java o comentarios xml en C #) es la técnica de documentación más importante. Facilitan la escritura de la documentación al mismo tiempo que escriben el código.
Si confía en volver y documentar las cosas más tarde, es posible que no lo haga, pero si lo hace mientras escribe el código, entonces lo que necesita documentarse estará fresco en su mente. C # incluso tiene la opción de emitir una advertencia de compilación si la documentación XML está incompleta o es inconsistente con el código real.
Pruebas como documentación
Otro aspecto importante es tener una buena integración y pruebas unitarias.
A menudo, la documentación se concentra en lo que las clases y los métodos hacen de forma aislada, omitiendo cómo se usan juntos para resolver su problema. Las pruebas a menudo los ponen en contexto al mostrar cómo interactúan entre sí.
Del mismo modo, las pruebas unitarias a menudo señalan dependencias externas explícitamente a través de las cuales las cosas deben ser simuladas .
También encuentro que usando el desarrollo basado en pruebas escribo un software que es más fácil de usar, porque lo estoy usando desde el principio. Con un buen marco de prueba, hacer que el código sea más fácil de probar y que sea fácil de usar a menudo es lo mismo.
Documentación de nivel superior
Finalmente, hay qué hacer con respecto a la documentación de nivel de sistema, arquitectura, desarrollador y posiblemente también del usuario final. Muchos abogarían por escribir dicha documentación en una wiki o usar Word u otro procesador de textos, pero para mí el mejor lugar para dicha documentación también es junto al código, en un formato de texto sin formato que sea amigable con el sistema de control de versiones.
Al igual que con la documentación en código, si almacena su documentación de nivel superior en su repositorio de código, es más probable que la mantenga actualizada. También obtiene el beneficio de que cuando extrae la versión XY del código, también obtiene la versión XY de la documentación. Además, si utiliza un formato compatible con VCS, significa que es fácil bifurcar, diferenciar y fusionar, al igual que su código.
Me gusta bastante primera , ya que es fácil de producir las dos páginas en HTML y documentos PDF a partir de ella, y es mucho más amigable que LaTeX , sin embargo, todavía puede incluir expresiones matemáticas de LaTeX cuando los necesite.
Cuando escribo código altamente matemático, también me parece útil tener algunos documentos wxmaxima en el repositorio de mi proyecto. Al ser texto sin formato, estos también se ramifican, difieren y fusionan muy bien, pero el uso de un sistema de álgebra computacional puede ayudarlo a verificar la coherencia de sus fórmulas y a documentarlas.