Escribir un registro de cambios que diga qué cambió y qué hay que hacer

## Saber quién lee el registro de cambios y qué cambios le afectan Escribe el registro de cambios para las personas afectadas por los cambios del software, no como una especificación validada por una máquina ni como un volcado sin procesar de la actividad de desarrollo. Cada decisión editorial debe ayudar al lector a entender la versión con menos esfuerzo. Antes de redactarlo, identifica: - La versión o publicación que se describe. - Las personas que dependen del producto, la biblioteca, el servicio o la documentación. - Los cambios que modifican el comportamiento, las expectativas, la compatibilidad, la accesibilidad, la seguridad o las acciones necesarias. - Las convenciones establecidas de numeración de versiones, encabezados y entradas que ya utiliza el proyecto. Utiliza las convenciones como herramientas, no como sustitutos del criterio. Conserva una estructura existente cuando ayude a los lectores a comparar versiones, pero no fuerces un cambio a adoptar una redacción engañosa solo para satisfacer una etiqueta. Cuando una regla deba ser estricta, explica el motivo para que quienes contribuyen puedan aplicarla con criterio. Mantén los principios del registro de cambios separados de las instrucciones de configuración y de los procedimientos habituales de contribución. Conserva una única ubicación autorizada para cada tipo de orientación y enlázala en lugar de duplicar instrucciones que pueden divergir con el tiempo. ## Incluir solo los cambios que afectan a quien lee y explicar por qué importan Revisa los cambios candidatos desde la perspectiva del lector. Incluye un elemento cuando cambie lo que una persona puede hacer, observar, considerar fiable, configurar, migrar o proteger. Excluye la actividad interna que no tenga un efecto significativo, salvo que explique una consecuencia relevante para las operaciones o la compatibilidad. Para cada cambio incluido, responde: 1. ¿Qué cambió en términos observables? 2. ¿A quién afecta y en qué condiciones? 3. ¿Por qué es importante el cambio? 4. ¿Debe actuar el lector y, de ser así, qué acción se requiere? Comienza por el resultado. Añade únicamente el contexto necesario para evitar malentendidos. Indica explícitamente las condiciones, las excepciones y las implicaciones para la migración; no las ocultes tras un resumen impreciso. No promociones una herramienta concreta solo porque sea popular ni inventes un proceso que no resuelva ningún problema de comunicación demostrado. Prefiere una entrada sencilla y el flujo de trabajo existente del proyecto, a menos que el enfoque actual impida a los lectores entender un cambio importante. Las directrices y recomendaciones deben incluir su justificación. El lector debe poder discrepar con conocimiento de causa porque la contrapartida y el beneficio previsto están a la vista. ## Escribir cada cambio con palabras sencillas, con su efecto y lo que hay que hacer Utiliza un lenguaje sencillo y presenta primero la idea principal. Evita poner barreras de acceso, la jerga abreviada de iniciados, la complejidad ornamental y las frases que obliguen al lector a reconstruir la afirmación principal. Prefiere una redacción que una persona no nativa pueda entender en la primera lectura y que un traductor pueda traducir directamente en vez de reinterpretar. Mantén diferenciados estos elementos: - El cambio en sí: una descripción concreta del comportamiento anterior y del nuevo. - El impacto: los usuarios, entornos, versiones o flujos de trabajo afectados. - El motivo: el problema resuelto o el principio protegido. - La acción: cualquier paso de actualización, configuración, migración o verificación que el lector deba realizar. No exageres la certeza ni el impacto. Si el comportamiento varía según el contexto, especifica la condición en lugar de emitir una orden universal. Si el lector no tiene que realizar ninguna acción, no inventes una. Usa la terminología de forma coherente en todas las entradas y versiones. Explica los términos especializados inevitables la primera vez que aparezcan, conserva las distinciones importantes y evita eufemismos que debiliten las advertencias o la información sobre cambios incompatibles. Aplica el mismo estilo claro y centrado en la idea principal a la documentación relacionada, las notas para contribuir y los mensajes de commit, de modo que el registro de cambios esté respaldado por información de origen coherente. ## Comprobar que las traducciones dicen lo mismo que el original y que decida una persona Trata las traducciones como comunicación de cambios de primera clase. Una traducción específica de una versión debe existir o proporcionar instrucciones claras para contribuir con ella. Debe seguir siendo exacta y coherente con la fuente canónica, además de resultar comprensible en su propio idioma y contexto cultural. Mantén la estructura de la página, el enrutamiento de versiones y el marcado de origen lo bastante sencillos como para que pueda editarlos un traductor que no sea programador. Antes de cambiar encabezados, identificadores, relaciones entre versiones o convenciones de marcado, evalúa cómo afecta el cambio a todos los idiomas y versiones que se mantienen. Utiliza esta secuencia de revisión: 1. Finaliza el significado de la entrada canónica antes de traducirla. 2. Registra qué versiones e idiomas requieren el cambio. 3. Comprueba que cada traducción requerida exista o disponga de una vía clara para contribuir con ella. 4. Compara el significado traducido con la fuente canónica para detectar omisiones, inversiones de sentido, condiciones alteradas y terminología incoherente. 5. Haz que una persona que conozca el idioma y la cultura tome la decisión editorial final. No utilices texto generado por máquinas como sustituto de un traductor. Las comprobaciones automatizadas o asistidas por modelos pueden localizar falta de cobertura y posibles incoherencias, pero las personas son responsables del significado, la adecuación cultural y la redacción final. ## Dejar las comprobaciones repetidas a herramientas sencillas y las decisiones a las personas Utiliza la automatización para reducir la verificación repetitiva entre idiomas, versiones y entornos de presentación. Entre los buenos candidatos se encuentran las comprobaciones de cobertura de traducciones, las pruebas de enrutamiento de versiones, las ayudas para la comparación semántica, las comprobaciones de accesibilidad y las pruebas de regresión visuales o funcionales. Prefiere herramientas corrientes y reutilizables que, una vez creadas, puedan ejecutarse de forma local o sin conexión y sin un modelo. Un modelo de lenguaje puede ayudar una vez a diseñar o implementar una herramienta, pero la comprobación resultante debe poder inspeccionarse y repetirse, ser económica de ejecutar y funcionar por sí sola. Los modelos no deben: - Sustituir a los traductores humanos ni a la revisión cultural. - Decidir las posturas editoriales del proyecto ni lo que significa su orientación. - Justificar una función o un proceso que no tenga una necesidad independiente. Las personas deciden si una entrada del registro de cambios es exacta, útil y adecuada. Las herramientas aportan pruebas; no son dueñas de la conclusión. Mantén el sistema de publicación sencillo y duradero. Prefiere la cadena de herramientas de compilación y creación existente, y añade una dependencia, un servicio, una base de datos o un nuevo entorno de ejecución únicamente cuando un requisito concreto no pueda satisfacerse de forma segura con el enfoque actual. Las herramientas de verificación exclusivas para el desarrollo no deben convertirse en requisitos innecesarios de producción. Antes de publicar, confirma que la entrada canónica sea clara, que las versiones y traducciones necesarias estén cubiertas, que las comprobaciones automatizadas tengan resultados reales y que una persona haya revisado el significado final.