¿Cómo lidiar con la versión de la documentation del software y el software en sí?

Necesito algunas experiencias relacionadas con la networkingacción de documentaciones de software y guías de usuario.

Cuando escribo documentos formales como especificaciones de software, cada documento obtiene un número de versión y en el documento hay un historial de cambios después de la tabla de contenido, donde puede realizar un seguimiento de los cambios realizados en el documento.

Si ahora estoy escribiendo una documentation de software o una guía de usuario para una aplicación, y el software tiene versiones propias, podría confundirse con el número de versión del documento y el producto: por ejemplo, la versión de la aplicación 1.5, la versión de la documentation 1.3.

¿Cuál es la forma / práctica recomendada de escribir la documentation del software? ¿Mantiene un logging de los cambios a los documentos allí? Si imprime un historial de cambios, ¿muestra cambios en el producto y / o el documento?

Creo que la documentation y el software son elementos diferentes, cada uno con diferentes numbers de versión. Desea poder actualizar la documentation sin tener que actualizar el número de software. Lo habría llamado algo así como:

Documentación del sistema para productX 1.3

Revisión de documentation 1.7

Al include claramente tanto la versión del software como la del documento en el mismo lugar, no debería haber confusión.

Tendemos a utilizar un formatting de text plano para nuestra documentation, principalmente LaTeX, y lo tratamos como código fuente desde el punto de vista de la revisión: va en el repository, podemos hacer diffs y parches, etc. No somos grandes para cambiar historias en documentos publicados, siempre podemos auditar lo que ha sucedido si es necesario pero rara vez lo es.

En cuanto a la synchronization de numbers de versión de código y documentation, nuestro enfoque preferido es que v1.1.1 de un documento coincide con v1.1.1 del software, 3.2.45 coincide con 3.2.45 y así sucesivamente. Sin embargo, en la práctica, a menudo solo tenemos documentation para los primeros 2 dígitos (es decir, 1.1, 3.2) ya que el tercer dígito es principalmente para corregir errores o mejorar el performance. El número de revisión del repo se inserta en la documentation (y en el código fuente) usando svn: palabras key si alguna vez lo necesitamos.

Me gustaría decirte que el mismo file MAKE que construye nuestra nueva versión de software también crea la nueva versión de la documentation, pero aún no lo hemos logrado. Sin embargo, estamos trabajando en ello.

Me he encontrado con este problema en todas las empresas para las que he trabajado que 1) tenía una base de códigos significativa, 2) intentaba documentation de calidad profesional, y 3) tenía grupos de desarrollo y documentation por separado.

He llegado a un acuerdo con Anders, convencido de que el software y la documentation deberían tener diferentes versiones y sistemas de control de versiones. Aunque son similares y tienen el mismo objective, la documentation y el código tienen ciclos de vida diferentes, que pueden ser completamente independientes, solo se asignan uno al otro en el momento del lanzamiento.

En cuanto a generar la documentation con cada compilation de software, pregúntese: ¿eso realmente tiene sentido? ¿La documentation es histórica o es prescriptiva? Cualquier documentation que se genera con cada compilation tiene mejores herramientas para hacerlo. Actualmente, eso solo funciona para la documentation de API y existen herramientas Doxygen- / Javadoc-style para soportarlo. Es probable que nunca sea factible para las Guías del usuario y las Guías de installation porque son sensibles al context.

La necesidad de diferentes sistemas de control de versiones se mantiene, en particular, para las nuevas metodologías de documentation estructurada. La documentation estructurada necesita ser administrada a un nivel mucho más fino de granularidad que el código fuente para poder manejar de manera eficiente algo incluso tan simple como cambiar la marca; generalmente se gestiona en el nivel de párrafo, oración o palabra, a diferencia del nivel de file, que es suficiente para el código fuente. Además, en general es económico que los elementos del documento se compartan entre múltiples productos o departamentos (ingeniería, marketing, …). Y, para este nivel de sofisticación de la documentation, solo un sistema de administración de contenido es suficiente para rastrear contenido y administrar el cambio; los SCCS CVS- / SVN- / Perforce- / Clearcase son abismalmente inadecuados para gestionar la documentation del mundo real. El uso de diferentes herramientas de gestión de versiones garantiza diferentes numbers de versión para la documentation y el software.

La documentation puede incluso tener una mayor tasa de cambio que el software cuando se considera la necesidad de manejar errores tipocharts, gtwigticales y de estilo corporativo.

Separar la documentation y los processs de desarrollo networkinguce las dependencies, que es la métrica fundamental necesaria para producir un producto de calidad. Además, es deseable la unión tardía para acomodar mejor la velocidad de cambio rápida y events impnetworkingecibles como adiciones o eliminaciones tardías de funciones. Solo en el momento de la versión final (o versión alfa / beta), la versión de la documentation debe asignarse a la versión del software. Pero, estoy de acuerdo con High-Performance Mark en que el usuario final no debe ver los diferentes numbers de versión. El número de versión de la documentation no necesita aparecer en el documento. Ese número puede, dentro del process de documentation, mantenerse y ocultarse al público.

La única vez que el control de versiones de software y documentation se puede mantener al mismo paso es cuando la documentation es una parte totalmente integrada del process de desarrollo. Durante los últimos 30 años, he visto que esto cada vez es less cierto porque hay un layout inicial less formal de lo que solía ser, confiando, en cambio, en un enfoque iterativo y de prototipado rápido para el desarrollo de software. Las nociones originales y bien intencionadas de tener documentation para impulsar el desarrollo de software se han dejado de lado, pero la nueva metodología tampoco nos ha proporcionado documentation o software mejorados. Ya sea que la documentation se realice de antemano o como una idea de último momento, aún duplicará el time que lleva desarrollar un producto de calidad comercial.

¿Por qué no utiliza el control de versiones y lo utiliza como la revisión automática de documentos? Puede hacer que la mayoría de los sistemas actualicen algún text al finalizar la compra.