¿Dónde poner la documentación del código?

Actualmente estoy usando dos sistemas para escribir documentación de código (estoy usando C ++):

• La documentación sobre métodos y miembros de la clase se agrega al lado del código, utilizando el formato Doxygen. En un servidor, Doxygen se ejecuta en las fuentes para que la salida se pueda ver en un navegador web
• Las páginas de descripción general (que describen un conjunto de clases, la estructura de la aplicación, el código de ejemplo, ...) se agregan a un Wiki

Personalmente, creo que este enfoque es fácil porque la documentación sobre los miembros y las clases está muy cerca del código, mientras que las páginas de resumen son muy fáciles de editar en el Wiki (y también es fácil agregar imágenes, tablas, ...). Un navegador web le permite ver ambas documentaciones.

Mi compañero de trabajo ahora sugiere poner todo en Doxygen, porque entonces podemos crear un gran archivo de ayuda con todo (usando HTML WorkShop de HTML o Qt Assistant). Mi preocupación es que editar la documentación al estilo de Doxygen es mucho más difícil (en comparación con Wiki), especialmente cuando desea agregar tablas, imágenes, ... (o hay una herramienta de 'vista previa' para Doxygen que no requiere que genere ¿El código antes de que pueda ver el resultado?)

¿Qué utilizan los grandes proyectos de código abierto (o de código cerrado) para escribir su documentación de código? ¿También dividen esto entre Doxygen-style y un Wiki? ¿O usan otro sistema?

¿Cuál es la forma más adecuada de exponer la documentación? ¿A través de un servidor web / navegador, o mediante un gran archivo de ayuda (varios de 100 MB)?

¿Qué enfoque toma al escribir la documentación del código?

Tener toda la documentación en un sistema en lugar de dos puede ser una verdadera ventaja. Cosas como copia de seguridad y restauración, control de versiones, búsqueda global, búsqueda y reemplazo global, enlaces cruzados y, como escribió, poner todos los documentos en un documento final, generalmente funcionará con menos "fricción" cuando no tenga que mantener dos diferentes sistemas con capacidades superpuestas.

Por otro lado, debe pensar si estas ventajas superan la facilidad de su Wiki. El círculo editar / generar / refinar editar / generar nuevamente puede ser más rápido con su Wiki. Supongo que puede obtener ese ciclo bastante rápido con doxygen manteniendo sus páginas de resumen como un subproyecto de doxygen separado. Puede hacer uso de las capacidades de enlace externo de doxygen, que no es un reemplazo para una "vista previa rápida", por supuesto, sino un paso hacia esa dirección. No lo he hecho solo, hasta ahora, pero supongo que debes probarlo por ti mismo si quieres saber si funciona en tu caso.

Con respecto a otros proyectos: creo que una herramienta como doxygen es principalmente para la documentación de la biblioteca. Si no es un proveedor de bibliotecas de terceros, y todos los que usan sus bibliotecas tienen acceso completo al código fuente, entonces la necesidad de una herramienta como doxygen es cuestionable. En nuestro equipo, por ejemplo, casi no tenemos documentos externos fuera del código, excepto los documentos de usuario final y los documentos de nuestros modelos de bases de datos. Nuestras herramientas principales para ese tipo de documentación son docbook y fop , lo que nos brinda resultados satisfactorios.

Utilice la documentación del código, primero. Agregue Wiki y otros métodos, si es posible

Lo sé, va a ser difícil mantenerlo.

Respuesta práctica:

En términos prácticos, lo primero que hacen los desarrolladores es verificar el código.

Como desarrollador, me gusta tener documentación externa, como Wiki (s), manuales. Pero, lo primero que hago es revisar el código (a veces de otros desarrolladores, a veces, el mío).

Como desarrollador, que trabajó en varios proyectos y clientes, hago lo posible para agregar documentación externa, pero es común tener mucha carga de trabajo y no poder soportar una wiki.

A veces, los gerentes de proyecto y otros jefes no se preocupan por la documentación, otras veces los desarrolladores no.

Y, lo mejor que puedo hacer es agregar algunos comentarios al código.

Buena suerte

Algunos usan otros sistemas: eche un vistazo a Python Sphinx, por ejemplo, tienen un sistema de documentos todo en uno que crea todo (también funciona para C / C ++)

Siempre pienso en la documentación como algo separado del código, doxygen es excelente, pero es para una descripción general de la API, no 'documentación'. Para eso, un wiki es excelente, pero prefiero usar ASCIIDOC y almacenar los resultados de eso en el control de origen junto con el código, principalmente porque puedo generar archivos PDF para entregarlos a otras personas (por ejemplo, los probadores, clientes, etc.)

Doxygen le permite crear PDF, HTML, páginas wiki, casi todo lo que se le ocurra.

Mi preferencia personal es tener Doxygen y wiki y un script o algo para verificar cuando divergen.

Desde la versión 1.8.0, doxygen admite Markdown , lo que debería hacer que la experiencia de escribir páginas estáticas sea tan conveniente como en un sistema Wiki.

Público objetivo

Creo que cuando responda esta pregunta, realmente debe preguntar quién debe leer esta documentación. Un desarrollador tiene necesidades muy diferentes a las de un usuario o incluso un analista de negocios.

• Como desarrollador: documentación asociada con el código que se está estudiando, detalles como el contrato de interfaz y ejemplos de uso. Quizás alguna documentación de alto nivel y especificaciones de protocolo para una buena medida.
• Como usuario: documentación disponible a través del menú de ayuda o un sitio web accesible sobre cómo usar el software.
• Como analista de negocios: la documentación disponible como documentos o como un sitio web accesible son útiles. Una cantidad modesta de detalles sobre protocolos, arquitectura de alto nivel y casos de uso son los mejores.

Mantenimiento

En cuanto a dónde ubicar la fuente de esta documentación dependerá de su audiencia y de quién está escribiendo para su audiencia.

• ¿Solo tienes una casa de desarrolladores? Coloca todo en el código. Lo alentará a que se actualice. Deberá trabajar en una cultura que fomente que las actualizaciones de documentación sean tan importantes como los cambios de código.
• ¿Tiene una casa de desarrolladores y escritores de documentación? Divide las responsabilidades. Use las herramientas orientadas al desarrollador para desarrolladores, use las herramientas de los escritores de documentación para los escritores de documentación.

Siempre que sea posible, asegúrese de que se puedan ejecutar ejemplos de código o casos de uso. Automatice su ejecución y señale internamente fallas. Lo más probable es que estas páginas sean documentación pobre o mala.

Además, independientemente de las herramientas que elija para escribir su documentación, necesita un medio confiable para asociar una versión específica de la documentación con una versión específica del código. Esto sigue siendo beneficioso incluso en terrenos felices en la nube con una única implementación de hoja perenne.

Documentación integradora

Puede ser necesaria la integración para producir cierta documentación, pero tenga en cuenta que solo el usuario espera un solo lugar para acceder a toda la documentación que necesita.

El analista de negocios está bastante satisfecho con una especificación de API, especificaciones de diseño y escenarios de uso que se ubicarán en documentos separados o secciones separadas de un sitio web.

El desarrollador prefiere todo lo visible desde la fuente, pero está muy contento de tener un par de documentos de diseño de alto nivel y documentos de especificación de protocolo detallados externos al código, aunque preferiblemente dentro del mismo proceso de pago.

Tu caso

Para ser honesto, la documentación en su wiki probablemente no sea el mismo tipo de documentación en su base de código. Puede que no tenga sentido fusionar también.

Por otro lado, la integración de los dos puede lograrse de varias maneras simples.

• Las herramientas de documentación de origen (como doxygen) pueden producir html, y una wiki vive en un servidor web. Sería un simple punto de integración simplemente servir una versión integrada junto con el wiki e interconectar los dos.
• Algunos productos wiki le permitirán ejecutar el wiki directamente desde un archivo que puede registrar en una base de código. Esto proporciona una herramienta de wysiwyg simple mientras mantiene la documentación emparejada con el código.
• También se pueden acomodar otros formatos como pdf, pero esto se reducirá a las herramientas específicas que desea utilizar. Puede tener sentido raspar su wiki en archivos de descuento y alimentarlo a través de doxygen (u otras herramientas). Puede tener sentido pdf el wiki y la fuente por separado y utilizar una herramienta de fusión de pdf.

Al final del día, descubra qué sistema de documentación tiene bajos costos de mantenimiento y lo ayuda a entregar un producto de alta calidad como lo ve su audiencia de Desarrolladores, Analistas de Negocios y Usuarios. Cualquier cosa que impida a cualquiera de estos grupos necesariamente reducirá la calidad de los productos.

Si está utilizando ASCII, debe almacenar sus datos de ocultar su documentación en la parte alta de su código fuente. Entonces solo los usuarios más inteligentes (léase: merecedores) tienen la oportunidad de usar sus documentos.

Tener documentación en un formato portátil bien definido, fácilmente exportable, podría ser la verdadera ventaja. Si la esfinge muere (poco probable) simplemente tendré que convertir a otro sistema, lo que supongo que sería una tarea programable. Mover datos fuera de la wiki (presumiblemente almacenados en la base de datos en un formato propietario podría ser una molestia).