Dado que un proyecto que estoy a punto de comenzar habrá documentación producida.Documentación y control de versión
¿Cuál es la mejor práctica para esto?
¿Deberían los documentos vivir con el código y los activos o debería haber un almacén de documentación por separado?
Editar
Me gustaría un wiki pero tendrá que imprimir los documentos, etc ... Es un proyecto universitario.
Realmente depende de su equipo. Donde trabajo, guardamos la documentación en un wiki que está vinculado con el sitio web de nuestro equipo. A los efectos de la documentación de envío, el wiki se puede exportar y lo ejecutamos a través de un analizador sintáctico que "fancifica" la apariencia de la documentación para los fines del cliente.
Almacenar la documentación con el código (normalmente en su repositorio de origen) no es una mala idea. Solo asegúrate de mantenerlos separados. Por ejemplo, mantenga una carpeta docs que esté en el mismo nivel que su carpeta src en su repositorio. De esta forma, puede enviar rápidamente la documentación actual, puede rastrear fácilmente las revisiones y cualquier persona nueva en el proyecto puede ingresar inmediatamente sin tener que ir a múltiples ubicaciones para obtener información.
Buen punto acerca de mantener los documentos en su propia carpeta. –
Almacenarlo en control de fuente está bien.
Si está escribiendo documentación de usuario versionada asociada con cada versión del producto, entonces tiene sentido poner la documentación en control de fuente junto con su versión de producto asociada.
Si está escribiendo documentación interna para desarrolladores, use documentación interna automatizada de código fuente (javadoc, doxygen, anotaciones .net, etc.) para documentación de nivel de fuente y una wiki de proyecto para documentación de nivel de diseño.
Creo que la mayoría de nosotros en la industria no estamos realmente siguiendo las mejores prácticas y, por supuesto, también depende mucho de su situación.
En un entorno ágil en el que tendría un proceso de liberación muy iterativo, querrá "viajar ligero". En este caso particular, la sugerencia de Jason de un Wiki separado realmente funciona muy bien.
En un modelo de caída de agua/Big Bang, tendrá una mejor oportunidad de tener una actualización de documentación decente con cada nueva versión. También deberá documentar claramente qué versión de los requisitos se acordó y tener un montón de documentación para cada cambio minúsculo que haga a los requisitos (debido a los efectos que tiene en etapas posteriores). A menudo, si la documentación puede vivir junto con el código fuente controlado por la versión, es la mejor.
¿Está utilizando algún tipo de auto-documentación o es completamente manual? Suponiendo que está utilizando un sistema de auto-documentación, la documentación se genera más o menos sobre la marcha, y sería parte del código en sí.
Para mí, (suponiendo que sea posible con cualquier código que esté usando), este sería el método preferido para manejarlo, ya que no necesitaría mantener la fuente de documentación en absoluto.
Esta es una pregunta interesante: básicamente, lo que otros dicen es correcto acerca de la documentación generada, los archivos fuente y las plantillas/etc.debe almacenarse en control de fuente y generarse durante su proceso de compilación.
En cuanto a los requisitos/especificaciones/etc. documentación, he trabajado en ambos sentidos, y prefiero usar SharePoint o un portal de Wiki/documentos diseñado para compartir documentos/versiones. La razón es que la mayoría de las personas que no son desarrolladores no se sienten cómodos trabajando con los sistemas de control de origen, y usted no obtiene ninguna de las ventajas de la fusión inteligente si está utilizando un formato binario como Word. Además, es agradable tener acceso basado en Internet para que pueda hacer referencia y trabajar en los documentos en un equipo distribuido sin que la gente tenga que instalar software adicional.
He aquí un resumen de las opciones 2017 y mi experiencia:
package-info.java archivos están infrautilizados.README.md) - Una buena solución a mitad de camino, con los beneficios de control de versiones. Si un solo archivo no es suficiente, considere una carpeta doc/. El único inconveniente de esto que he visto es si los gráficos de utilidad de control de origen (por ejemplo, archivos png) y riesgo de hinchazón del repositorio.
éxito de Github es en gran parte gracias a sus README.md ubicados en la raíz del proyecto.
¿Está esta documentación de nivel de usuario o documentación de desarrollador? – nall
Es todo. Desafortunadamente es un proyecto universitario. – Finglas
Los documentos están escritos en Office como aptos para ser documentos en línea y es una mezcla de contenido manual y generado automáticamente. – Finglas