A medida que la tecnología avanza y los flujos de trabajo se agilizan, algunos han recurrido a herramientas automatizadas como Doxygen , Sphinx , Swagger , etc. para generar documentación técnica automáticamente.
¿Cuáles son las limitaciones más evidentes de estas herramientas y cómo se pueden abordar con el fin de ahorrar tiempo a quienes realizan la documentación?
Doxygen, etc. en realidad no generan documentación automáticamente. Reestructuran y dan formato a la información escrita a mano, ya sea en forma de código (que es una forma de datos estructurados) o comentarios escritos en el código. Formatean y publican la información automáticamente. No generan contenido automáticamente.
Para mí, la limitación más evidente de estas herramientas es que constituyen una cadena de herramientas de publicación separada que no está relacionada con la cadena de herramientas utilizada para el resto del conjunto de documentación. Esto significa que primero tiene que hacer todo el trabajo de configuración y mantenimiento de la cadena de herramientas y la presentación y formateo de su contenido dos veces. Y debido a que todos estos tienen motores de publicación relativamente rudimentarios, a menudo no se puede lograr que su salida coincida con el diseño del resto del conjunto de documentación.
El segundo problema con esto es que significa que no hay integración entre el contenido que producen y el resto de tu contenido. Antes, esto era una preocupación menor, pero ahora que publicamos principalmente en la Web, se hace más difícil hacer cosas elementales como generar enlaces a partir de las menciones de una función en la guía del programador a la lista de esa función en la referencia de la API.
La cura para estos problemas es tomar la salida XML de estas herramientas e introducirla en la cadena de herramientas general. Por supuesto, esto supone que su cadena de herramientas general está basada en XML o al menos es capaz de recibir e integrar una fuente XML. Este no es el caso de la mayoría de las herramientas de escritura y publicación estándar. El resultado es que sus documentos API quedan como una isla.
Los sistemas automatizados como Sandcastle y Swagger son buenos para convertir la sintaxis del código en documentación. Esos producirán documentación marginal. Lo que no hacen es agregar información sobre las llamadas. Rara vez existe un método por sí mismo. Siempre se necesitan notas adicionales, advertencias explicadas, efectos secundarios, aclaraciones para cada parámetro, valores devueltos, el método en sí e incluso el uso del método en un contexto más amplio. Compare, por ejemplo, una página de referencia típica de MSDN con una página de referencia REST cualquiera. Para cada método, la página de MSDN es más larga y detallada, el material que desean los desarrolladores. Los REST suelen ser escasos con menos notas adicionales.
Luego hay ejemplos y fragmentos de código. Ninguna aplicación generada automáticamente puede hacer eso. Mucha gente no entiende la documentación de la API. El 95 % de las veces, los desarrolladores solo quieren una muestra para copiar y pegar. La documentación automatizada rara vez los genera.
Muchos piensan que con poder usar una página de referencia es suficiente. No es. Es la facilidad y la integridad en la forma en que se responden las preguntas lo que cuenta. Esta es la diferencia entre la documentación adecuada y la gran documentación.
adam michael madera
EJoshuaS - Apoya a Ucrania