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.