Cómo realizar un seguimiento de las solicitudes de cambio sobre un documento funcional

TL;RD

Su suposición de que necesita realizar un seguimiento de los cambios en varias revisiones limita el alcance de las opciones de control de cambios. También lo es su uso del formato de Microsoft Word. Reconsideraría ambos a menos que puedas:

• asegúrese de tener un solo propietario de documento, y
• realice un seguimiento de los cambios textuales independientemente de su proceso de aprobación de control de cambios.

Sin embargo, si no puede cambiar sus suposiciones o su cadena de herramientas, he incluido algunas sugerencias sobre cómo enviar cambios a través de un propietario de documento centralizado e implementar el seguimiento de revisiones que pueden resultar útiles. Su experiencia puede ser diferente.

Tipos de artefactos de documentos

Documentos vivos frente a documentos de referencia

Un documento vivo cambia a medida que avanza un proyecto. Por ejemplo, un documento de especificación puede obtener actualizaciones cuando la característica foo se reemplaza por la barra de características , o cuando la característica baz se modifica de alguna manera. Este tipo de documento vivo puede tener firmas o aprobaciones, pero no pretende compararse con versiones heredadas de sí mismo y, por lo tanto, es relativamente fácil de mantener.

Un documento de referencia es un artefacto histórico. Puede crear una especificación de referencia al comienzo de un proyecto y luego crear nuevos documentos de especificación según sea necesario durante la vida del proyecto. Todos estos documentos se mantienen como artefactos del proyecto, pero no es necesario que sean revisiones o incluso directamente comparables. Son simplemente instantáneas de las especificaciones del proyecto en momentos determinados.

Documentos bastardos

Estoy usando deliberadamente el término documentos bastardizados en lugar de "híbrido" o "edición compartida" porque la necesidad de un seguimiento de cambios complejo generalmente es el resultado de una edición ad-hoc . Por ejemplo, si enruta un documento a 37 personas, todas las cuales pueden realizar revisiones directamente en el documento, esos cambios deben fusionarse, resolverse los conflictos y debe implementarse algún tipo de seguimiento de los cambios.

Asigne la propiedad del documento para preservar la cordura

Los cambios gratuitos son generalmente solo una mala idea ™. Recomiendo encarecidamente un enfoque más simple donde:

1. Los documentos tienen un único propietario.
2. Los documentos están numerados por línea.
3. Las personas pueden enviar solicitudes de cambios, haciendo referencia a los números de línea según sea necesario, al propietario del documento.
4. El propietario del documento realiza cambios y los envía al organismo de aprobación cuando es necesario.
5. Si es necesario, las solicitudes de cambio se pueden conservar como artefactos históricos.

Una vez más, esto es en gran medida independiente de la cuestión del seguimiento de cambios dentro del propio documento. Sin embargo, los sistemas de control de revisión reales (piense en SVN o Git) pueden cumplir algunos de los mismos propósitos y también rastrear el historial completo de revisiones textuales. Más sobre eso a continuación.

El valor de rastrear versiones históricas

Si realmente hay algún valor en esto es realmente una cuestión política. Desde un punto de vista práctico, lo que solían ser las especificaciones es menos útil que lo que el producto/característica debe hacer ahora .

El seguimiento de la versión (o revisión) es realmente un problema independiente del control de cambios. Para el control de cambios, debe poder definir los cambios (y quizás los casos comerciales asociados) y obtener las aprobaciones adecuadas para las nuevas especificaciones futuras. Si los cambios son sutiles, a veces es útil ver las versiones actuales y futuras una al lado de la otra para que las diferencias sean más obvias, pero la función central del control de cambios es que está autorizando los cambios, en lugar de seguimiento de versiones históricas.

Con eso en mente, solo necesita realizar un seguimiento de la versión aprobada más recientemente y la versión nueva (actualmente no aprobada). Esto viola sus suposiciones como se describe en la pregunta original, pero puede valer la pena considerarlo.

Seguimiento de revisiones históricas por separado del control de cambios

La forma de hacerlo depende en gran medida de la implementación técnica del proceso. Si debe seguir con MS Word, podría considerar:

1. Siempre manteniendo el seguimiento de cambios activado.
2. Agregue notas ocultas que atribuyan cambios específicos a personas, reuniones o hitos que no son capturados por el seguimiento de cambios.
3. Oculte los cambios/notas a menos que esté haciendo algún tipo de arqueología de documentos.

Esto funciona hasta cierto punto, pero se vuelve desordenado y confuso con bastante rapidez. Si usa un formato más flexible como OpenOffice o Markdown, o incluso solo una utilidad para volcar texto de Word a ASCII según sea necesario, puede almacenar revisiones textuales en un sistema de control de código fuente como Git. Personalmente, a menudo uso Markdown o AsciiDoc como formato de documento nativo para poder almacenar revisiones textuales en Git y uso Pandoc para imprimir los documentos en formato PDF, HTML o Word cuando sea necesario.

Esto separa la complejidad del control de revisiones del proceso de control de cambios. Permite explorar el historial de revisiones para realizar comparaciones en paralelo de cualquier par arbitrario de revisiones, así como la inclusión de notas y explicaciones en el historial mismo (p. ej., registros de Git o notas de Git ).

Ejemplo de modelo de propietario del documento con control de revisión

Como ejemplo del modelo de propietario del documento junto con un formato de fuente basado en texto y un sistema de control de revisión, considere lo siguiente. Si Bob es el propietario del documento y Alice no es lo suficientemente inteligente como para editar Markdown o realizar cambios en Git ella misma, entonces Alice podría enviar una solicitud de cambio de documento a Bob diciendo:

Cambie la línea 17 para decir "embiggen the widget" en lugar de "minify the monolith".

y Bob puede realizar los cambios, atribuírselos a Alice y enviar el nuevo documento a través del proceso de control de cambios para su aprobación.

Opciones basadas en procesador de textos

Su millaje variará mucho si no usa un formato nativo basado en texto o no usa un sistema de control de revisión. Sin embargo, se pueden hacer cosas similares (aunque de forma más limitada) con documentos de Word y LibreOffice, cada uno de los cuales admite varios tipos de seguimiento de cambios , control de versiones de documentos y comparación de versiones .

Si estas características satisfacen sus necesidades, ¡genial! Si no, al menos ahora tiene algunas alternativas a su proceso o cadena de herramientas que puede considerar.

Un problema común. Hay algunos enfoques, pero este es el que uso:

1. Cada cambio o conjunto de cambios se captura en un nuevo documento de solicitud de cambio. El documento CR debe capturar los nuevos requisitos con tanto detalle como sea necesario para a) aprobarlos b) realizar el análisis de requisitos funcionales c) hacer una estimación razonable del esfuerzo requerido para implementar el cambio (no solo el desarrollo sino todo el proceso posterior). impacto de implementar el cambio). Asegúrese de que las personas adecuadas en el equipo de desarrollo estén incluidas en la revisión/aprobación para que sepan lo que viene.

2. Cada CR es evaluado por la junta del proyecto/la empresa/el patrocinador/quien sea más apropiado para determinar si vale la pena pagar el costo del cambio dados los beneficios que traerá.

3. Si se aprueba el CR para continuar, pasa a la fase de análisis funcional detallado. Asegúrese de decirle al equipo de desarrollo que fue aprobado para que sepan lo que viene. El documento previamente aprobado se eleva a una nueva versión menor, es decir v1.0 a v1.1 (teniendo cuidado de mantener una copia de la versión original). Se activa el seguimiento de cambios y el documento se actualiza en todos los aspectos para cubrir el CR. En el historial de edición, hace referencia a que esta nueva versión contiene las enmiendas relacionadas con CRxxx y, lo que es bastante importante, enumera los cambios principales en la parte del historial de edición de la especificación, por ejemplo, la Sección 1.2 cambió para incluir el nuevo widget, la Sección 2.7.1 cambió para incluir el nuevo widget en el ámbito de integración, etc., etc.

4. Cuando se hayan realizado todas las enmiendas, debe ir para su aprobación al mismo grupo de personas que aprobó el CR. Pueden usar el seguimiento de cambios para ver exactamente qué se ha cambiado, o ver/imprimir el documento en Final sin marcas si así lo desean. Revisan que se hayan realizado todos los cambios y están contentos con la nueva versión. Los signatarios de la especificación funcional también deben revisar el documento modificado.

5. Repita tantos ciclos de revisión/cambio como sea necesario hasta que los signatarios aprueben la especificación modificada. Luego guárdelo en una nueva copia, eleve el número de versión al siguiente número entero (es decir, de v1.3 a v2.0), agregue una línea en su sección de historial de edición con un comentario que diga Versión aprobada Y ACEPTE TODOS LOS CAMBIOS. Guárdelo en la ubicación central del proyecto, archive todas las versiones anteriores y distribúyalo a todos los que lo necesiten con instrucciones de que reemplaza todas las copias anteriores. Revíselo con el equipo de desarrollo, hable sobre los cambios, planifique los cambios en el proyecto y asegúrese de que todos los desarrolladores estén a bordo.

He visto esto en mal estado en varias ocasiones y generalmente se debe a las siguientes razones. No caiga en la tentación de tratar de acortar el proceso, eventualmente le costará:

1. Los nuevos cambios se capturan en una nueva especificación solo para ellos, que finalmente se aprueba y pasa a los desarrolladores además de la especificación original. Esto es una pesadilla: terminarás con diferentes personas desarrollando con diferentes especificaciones.

2. Las personas pasan por alto los cambios sin documentarlos, estimarlos y considerar adecuadamente el impacto.

3. Las personas solo les piden a los desarrolladores que calculen los cambios/adiciones y se olvidan de incluir el equipo de prueba/control de calidad, el equipo de hardware y el equipo de infraestructura, oh, y el administrador de versiones, y los BA y el equipo de MI con quienes tienen que lidiar. los datos posteriores y entregar informes modificados... etc. etc. No haga esto: envíe la ronda CR a todos los departamentos involucrados en el proyecto para que puedan evaluar el impacto del cambio, luego tome en cuenta ese impacto en los presupuestos del proyecto.

4. Las personas no mantienen un registro de los CR, por lo que una vez que hay más de tres, todo se vuelve un poco confuso.

5. La gente no mantiene el registro en papel de las versiones y los documentos CR, por lo que se vuelve imposible en el plazo de un año averiguar qué se cambió y cuándo.

6. Las personas nunca regresan y aceptan los cambios y desactivan el seguimiento. Por lo tanto, los cambios se acumulan de una versión a otra y, finalmente, es imposible leer correctamente el documento.

7. La gente dice "hagamos el cambio y nos pondremos al día con todas las fusiones de documentos más tarde"... NUNCA sucede, y antes de que sepa dónde se encuentra, el proyecto se especifica en 23 lugares diferentes, cada uno con matices de versiones, entendimientos y estimaciones.

Básicamente, implemente un control de cambios consistente, documente y realice un seguimiento de sus cambios, incluso si son rechazados. Mantenga, en la medida de lo posible, una única versión central de "la verdad" y asegúrese de que todos estén trabajando para lograrla. Esto puede convertirse en un problema por derecho propio, pero siga adelante, no importa cuán arduo se vuelva, siempre será mucho más una pesadilla tratar de comprender retrospectivamente cuál se suponía que era la especificación en ausencia de control de cambios y un rastro de papel.