La documentación de PostgreSQL es excelente. Algún consejo de como lograr eso con otros productos más allá de usar LateX? Me interesa saber si los programadores deben documentar o lo debe hacer un tercero dedicado a eso. Se oyen recomendaciones.
Escribe los manuales en Markdown y usa Pandoc para publicar en el formato que te interese. No hay cosas más flexible hoy en día. Markdown es texto puro, la sintaxis es ridículamente simple, lo administras con tu VCS, y se puede manipular en cualquier editor de programación (algunos hasta modo «preview» tienen).
Para la documentación técnica, es importante que los lenguajes que uses tengan un mecanismo de documentación embebida inteligente (como Perl Pandoc o Haskell Haddock), o bien mecanismos de «literate programming» en los cuales el compilador extrae la documentación (escrita en Markdown o LaTeX) para su procesamiento.
Si un programador no es capaz de articular con claridad y precisión cómo funciona su código, cómo interactúa con el resto del sistema, y cuáles son las condiciones especiales de uso, no lo está haciendo bien. Programar es el arte de que otra persona comprenda lo que tu código logra que la computadora haga -- buen código, buena documentación.
Para la documentación técnica, es importante que los lenguajes que uses tengan un mecanismo de documentación embebida inteligente (como Perl Pandoc o Haskell Haddock), o bien mecanismos de «literate programming» en los cuales el compilador extrae la documentación (escrita en Markdown o LaTeX) para su procesamiento.
Si un programador no es capaz de articular con claridad y precisión cómo funciona su código, cómo interactúa con el resto del sistema, y cuáles son las condiciones especiales de uso, no lo está haciendo bien. Programar es el arte de que otra persona comprenda lo que tu código logra que la computadora haga -- buen código, buena documentación.
Liked by:
Walter Vargas
Marcos Mora