¿Cómo se evitan cambios incompletos en la documentación?

Es este un problema difícil. A menos que su empresa tenga los recursos para realizar revisiones completas de toda la documentación en cada versión, y si lo hacen, me pregunto cómo se mantienen competitivos, entonces está en riesgo aquí. En mi experiencia, puede hacer algunas cosas para abordar el problema cuando sucede, y algunas cosas para reducir la posibilidad de que ocurra .

Aquí hay técnicas que he usado para encontrar y corregir actualizaciones faltantes:

• Escaneo visual rápido de la documentación más relevante. Esta no es una revisión completa (probablemente no tenga tiempo), pero trato de pasar mis ojos por lo menos sobre cada página en documentos/secciones relacionadas para tener la posibilidad de que algo me llame la atención. Esto realmente sucede.

• Si se cambió o eliminó una función (función de API, elemento de GUI, elemento de esquema, etc.), busco en la documentación palabras clave relevantes como el nombre de la función/elemento (sin embargo, hablamos de ello en la documentación). Esto ayuda a encontrar referencias perdidas, como la documentación de alguna otra función que la compare con la que cambió. Esto me ha ayudado a detectar casos como "La función X hace bla, bla, bla; es similar a la función Y excepto..." donde Y cambió.

• Si el comportamiento cambió, entonces los casos de prueba probablemente también cambiaron. Intento conversar con los evaluadores que probarán la función recién modificada para averiguar qué otros casos de prueba tuvieron que cambiar. (Nota: aunque tengo acceso a su repositorio de casos de prueba, me resulta más fácil pasar un poco de tiempo hablando con un probador. Los probadores conocen sus casos de prueba mucho mejor que yo. Por razones similares, generalmente preguntan decirme qué cambios significativos hice en la documentación).

• En un proyecto con varios escritores, elijo revisores pares que han trabajado en partes de la documentación en las que no he dedicado tanto tiempo. Notarán "oh, si eso cambió, entonces esta otra cosa en 'mi' documento también debe cambiar" antes de que yo lo haga.

Aquí hay algunas técnicas que he usado para prevenir, o al menos reducir la probabilidad de este problema. Piense en esto como una escritura defensiva :

• En el espíritu de "no te repitas" (DRY), si necesito incluir la misma información en más de un lugar, trato de abstraerla en una sola mancha que puedo incluir por referencia en todos los lugares que necesita Vamos. Escribir documentación fragmentada como esta es más difícil (debe tener cuidado para asegurarse de que su blob siga siendo válido en todos los contextos), pero este nivel de repetición no ocurre tanto en mi experiencia. Pero sucede algo, así que use las herramientas de inclusión cuando suceda.

• A veces, cuando estás escribiendo algo, sabes que está interconectado con alguna otra parte de la documentación. Use comentarios (o cualquier mecanismo de anotación compatible con su herramienta) para agregar recordatorios que pueda encontrar. Los comentarios no son solo para el código; también pueden ser útiles en la fuente del documento. (Mi fuente es XML; su kilometraje puede variar).

• Todavía no he hecho este en "producción" (solo como prueba), pero anote sus capturas de pantalla .

• Cuando se trata de su base de datos de errores, sea entrometido. Me copian automáticamente todos los errores en ciertos componentes, y reviso nuevos errores con frecuencia y me agrego a la lista de CC en cualquiera que parezca que podría afectarme. Sí, esto genera una gran cantidad de correo electrónico, pero vale la pena leer las notas de los evaluadores y también las de los desarrolladores que descubrieron que tenían que cambiar algo más para implementar esto. Obtengo mucha de mi mejor información de las notificaciones de Bugzilla.

• Sea más minucioso en la estimación inicial del proyecto. Al comienzo del ciclo de planificación del lanzamiento, cuando el gerente de producto, el equipo de desarrollo y otros están diseñando el trabajo a realizar, probablemente, si es como la mayoría de las personas, agregó una línea al plan del proyecto que dijo algo así como "actualizar doc (N semanas)". Pero si hace un poco más por adelantado, puede evitar algunos problemas para usted y para los evaluadores. ¹Mientras los desarrolladores hacen su análisis de lo que cambiará si hacen tal o cual cosa, usted puede estar haciendo lo mismo con el documento. Entonces, en lugar de esa línea "actualizar documento", puede tener elementos como "documentar nueva función X", "actualizar función Y (que cambió debido a X)", "actualizar documento de ejemplo que usa Y y Z" y "revisar documento de Y para el impacto". Mientras habla con su amable evaluador sobre esto, puede aprender que su evaluador sabe que una parte de Z también tendrá que cambiar, por lo que puede comenzar a pensar en eso antes. En otras palabras, cuanto más hable su equipo sobre el impacto desde el principio, más fácil le resultará hacer cambios en su documento de manera sistemática y con menos prisas al final.

¹ Es posible que ya se haya dado cuenta de que creo que los evaluadores son sus aliados naturales. Son. Usted y ellos a menudo se encuentran al final del flujo de información, no porque alguien haya querido excluirlos, sino porque las personas que se enfocan en una tarea limitada no siempre se dan cuenta de las implicaciones por sí mismas. Trabajar juntos.

El código ya es una forma de documentación de lo que hace el sistema. Ese es más bien el objetivo del código de lenguaje de alto nivel, facilitar la comprensión de los sistemas para los lectores humanos.

Esta es una pista para una solución. Pregúntese, "¿para quién es la documentación?" ¿Es para que los programadores se comuniquen con otros programadores dentro de su organización? Luego haga lo que pueda para que el código sea claro, conciso, no sorprendente y SECO. DRY es más sobre el futuro que sobre el presente.

Y no tiene sentido conservar documentación rota. Sería mejor descartar los documentos y eliminar cualquier posibilidad de que alguien pueda cometer un error técnico al confiar en documentación potencialmente errónea. No se sabe que la mala documentación sea mala hasta que te explota en la cara. Hasta entonces, proporciona una falsa sensación de seguridad.

¿Es para un administrador de programas? Luego busque escribir documentación que sea clara, concisa y que no se esconda detrás de palabras técnicas de moda y falsa jerga legal. La mayoría de la gente no se mantiene al día con la documentación porque les resulta difícil entender lo que ya está escrito, es difícil emular el estilo y desprecian hacer trabajos improvisados. No tiene mucho sentido poner detalles técnicos minuciosos en la documentación. De lo contrario, habríamos diseñado un lenguaje de programación que utiliza documentos de MS Word como archivos fuente.

¿Es para los usuarios? Entonces su documentación es parte de su producto. Debe dedicar un tiempo específico, y probablemente personas específicas que hacen carrera escribiendo documentación de uso, a las tareas. La iteración del proyecto no es más completa sin la documentación del usuario, una forma de interfaz de usuario, que las características que cubriría. Tiendo a preferir poner ese texto explicativo en la pantalla junto a la función.

Y eso es generalmente un problema con todas las partes de un sistema: ¿qué tan cerca están los componentes estrechamente acoplados? Verá que sucede en las definiciones de esquema de su base de datos si las administra a través de scripts SQL sin procesar. Sucederá con los informes generados en su sistema si el código del informe está "lejos" de la interfaz de usuario del informe. Mantener las partes relacionadas del sistema ubicadas juntas es la única forma de evitar que se separen, como dos muestras de una especie que divergen con el tiempo después de ser separadas por un océano.

También tenga en cuenta que no tiene que seguir el proceso "obvio" para escribir documentación que a los administradores de programas siempre parece gustarles. La última vez que trabajé en un entorno muy documentado, dediqué al menos el 50 % de mi tiempo a la documentación. Pero aunque mi administrador de programas quería que la documentación se escribiera antes que el código, no hice tal cosa. Los escribí en tándem. Necesitaba escribir el código para averiguar qué incluiría en la documentación. Fui elogiado por tener la mejor tasa de documentación y entrega en la empresa.

Pero la moraleja de la historia no es "hazlo a mi manera". Es que cada empresa tiene su propia cultura que valorará ciertas cosas sobre otras. Usa ese conocimiento a tu favor. Roba tiempo de codificación del tiempo de documentación o viceversa. Escriba cualquier código que necesite para automatizar tareas repetitivas. Cuestionar aseveraciones fundamentales y buscar minimizar la carga de trabajo.