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

Tener toda la documentación en un sistema uno en lugar de dos puede ser una ventaja real. Cosas como copia de seguridad y amp; la restauración, el control de versiones, la búsqueda global, la búsqueda global y la sustitución, la reticulación y, al escribir, colocar todos los documentos en un documento final, normalmente funcionará con menos "fricción" cuando no tenga que mantener dos sistemas diferentes con Capabilites superpuestos.

Por otro lado, debes pensar si estas ventajas superan la facilidad de tu 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 utilizar las capacidades de enlace externo de doxygen, que no es un reemplazo para una "vista previa rápida", por supuesto, pero un paso hacia esa dirección. No he hecho esto solo, hasta ahora, pero creo 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 base de datos. Nuestras herramientas principales para ese tipo de documentación son docbook y fop , que nos da resultados satisfactorios.

Use la documentación del código, primero. Añadir Wiki & 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 & clientes, hago lo posible por agregar documentación externa, pero es común tener una gran cantidad de trabajo y no se ha podido admitir una wiki.

A veces, los gerentes de proyecto, & a otros jefes, no les importa la documentación, a veces otros desarrolladores no lo hacen.

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

Buena suerte

Doxygen te permite crear PDF, HTML, páginas wiki, casi todo lo que puedas imaginar.

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

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

Siempre pienso que la documentación está separada del código, doxygen es genial, pero es para una descripción general de la API, no para "documentación". Para eso, un wiki es genial, pero prefiero usar ASCIIDOC y almacenar los resultados de ese control de código fuente junto con el código, principalmente porque puedo generar archivos PDF de ellos para que sean entregados a otras personas (por ejemplo, los evaluadores, el cliente, etc.)

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 respondas a esta pregunta, realmente necesitas preguntar quién debe leer esta documentación. Un desarrollador tiene necesidades muy diferentes a un usuario o incluso a 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. Tal vez 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. Lo mejor es una cantidad modesta de detalles sobre los protocolos, la arquitectura de alto nivel y los casos de uso.

Mantenimiento

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

• ¿Sólo tienes una casa de desarrolladores? Coloca todo en el código. Se animará a que se actualice. Deberá trabajar en una cultura que fomente que las actualizaciones de la 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 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. Automatiza su ejecución y marca internamente las fallas. Lo más probable es que estas páginas tengan mala o mala documentación.

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 Happy Cloud con un solo despliegue de hoja perenne.

Integración de documentación

La integración puede ser necesaria 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 las especificaciones de API, las especificaciones de diseño y los escenarios de uso que se ubicarán en documentos separados o en secciones separadas de un sitio web.

El desarrollador prefiere todo lo visible desde la fuente, pero está feliz 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 de la misma verificación.

Su caso

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

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

• Las herramientas de documentación de origen (como doxygen) pueden producir html, y un wiki vive en un servidor web. Sería un punto de integración simple simplemente servir una versión construida junto con el wiki y vincular los dos.
• Algunos productos de wiki te permitirán ejecutar el wiki directamente desde un archivo que puedes ingresar a una base de código. Esto proporciona una herramienta wysiwyg simple a la vez que mantiene la documentación vinculada al código.
• También se pueden acomodar otros formatos, como el pdf, pero esto se reducirá a las herramientas específicas que desea utilizar. Podría tener sentido raspar su wiki en archivos de rebajas y alimentarlo a través de doxygen (u otras herramientas). Podría tener sentido hacer un pdf de la 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 cualquiera de estos grupos necesariamente reducirá la calidad de los productos.

¡Si está utilizando ASCII, debe guardar su información de documentación oculta en la parte alta de su código fuente! Entonces, solo los usuarios más inteligentes (leídos: merecedores) tendrán la oportunidad de usar sus documentos.

La ventaja real es tener documentación en un formato portátil, fácilmente exportable y bien definido. Si sphinx muere (es poco probable) me convertiré a otro sistema, lo que supongo que sería una tarea programable. Mover datos fuera de wiki (presumiblemente almacenados en una base de datos en un formato propietario puede ser una molestia).