Documentación en un sistema de control de versiones

Ya he visto esta pregunta: Documentación y control de versiones

Ahora la pregunta es, ¿qué tipo de documentation es adecuada para el control de versiones? Pienso en la documentation interna y de usuario. Esta documentation podría generarse, pero también podría ser files de text sin formatting, aunque esta es la última opción. El problema es que la documentation debe ser fusionable (debido al trabajo con sucursales), como ocurre con el código fuente. Así que los documentos de OpenOffice, PDF y wikis basados ​​en bases de datos serían un problema, supongo. Los files de text sin formatting serían una opción. Quizás Latex o HTML. ¿Pero hay otras buenas maneras de documentar las cosas? Un wiki sería muy bueno para la documentation interna. Algo como git-wiki podría ser apropiado, creo, pero no usamos git. Por lo tanto, sería mejor si es independiente de VCS.

¿Hay alguna recomendación? ¡Gracias!

El control de fuente es bueno para dos cosas cuando se trata de datos de text (código o documentation):

  • comparación (¿qué ha cambiado de una versión a otra?): es por eso que los formattings binarys no son muy útiles en un VCS.
  • fusionarse (informando un esfuerzo de desarrollo aislado de una twig a otra), es por eso que la wiki no siempre se adapta, ya que su contenido evoluciona principalmente de forma secuencial (en otras palabras, sin twig)

Cualquier tipo de documentation textual, con un tipo de lenguaje de marcado neutral (como un descuento ) está bien si asocia dicha documentation con otros datos (principalmente el código) que necesitan control de versiones y fusión.

Los files PDF e incluso los documentos de Office no son "fonts" adecuadas, como correctamente descubrió. Existen kits de herramientas para documentation técnica, como DITA Open Toolkit , que le permiten utilizar realmente el código fuente (por ejemplo, en forma de files XML cuando usa DITA) para la documentation y generar cualquier formatting de salida que desee de una forma process de construcción.

Esos pueden, por supuesto, agregarse correctamente a su solución de versiones, y al fusionar la continuous integration y las testings automatizadas, puede generar automáticamente capturas de pantalla y otros artefactos que luego se utilizan para build siempre y automáticamente una documentation actualizada de su producto.