Escribir un documento de diseño (RFC) sobre el que quienes revisan puedan decidir

Objetivo

Que un cambio de gran alcance lo decidan las personas que tendrán que convivir con él, a partir de un documento que pueda leerse en veinte minutos y antes de que alguien escriba el código. Más adelante, ese mismo documento sirve como constancia de por qué el sistema es como es.

Requisitos previos

Un cambio que resulte demasiado grande o demasiado controvertido para la descripción de un pull request; personas revisoras conocidas y con la facultad de aprobar; un lugar junto al código (un directorio docs/rfcs/, un archivo numerado, un pull request). PEP 1 y la plantilla de RFC de Rust son ejemplos públicos de tales procesos. El capítulo de documentación de «Software Engineering at Google» constata que las plantillas usadas allí exigen tener en cuenta la seguridad, la internacionalización, los requisitos de almacenamiento y la protección de datos, y que estas partes suelen ser revisadas por especialistas de cada área.

Pasos

1. Describir el problema antes que cualquier propuesta: quién se ve afectado, qué ocurre hoy, qué condición del entorno obliga a un cambio. Si el problema no puede expresarse en un párrafo, el documento no está maduro.
2. Enumerar los objetivos como afirmaciones numeradas y verificables, junto con los no objetivos que delimitan el alcance. Los no objetivos evitan que la revisión se desborde hacia deseos colindantes.
3. Explicar la propuesta dos veces, tal como prevé la plantilla de Rust: una a nivel de usuario (cómo se ve el cambio para quien lo usa), y otra a nivel de referencia, con la semántica exacta, los formatos y los casos límite.
4. Dejar constancia de las alternativas consideradas y por qué se descartó cada una. PEP 1 prevé una sección de ideas descartadas junto con su justificación, para que la misma idea no vuelva a plantearse; la plantilla de Rust tiene para ello «Rationale and alternatives».
5. Nombrar con honestidad las desventajas, las consecuencias de compatibilidad, la migración y el despliegue, así como los costos operativos; un documento sin desventajas se lee como publicidad.
6. Cerrar con las preguntas abiertas, separadas en «debe decidirse en esta revisión» y «puede aclararse durante la implementación».
7. Distribuirlo con un plazo para su revisión, responder a los comentarios en el propio documento en lugar de en el chat, y dejar constancia del resultado en una línea de estado (borrador, aceptado, rechazado, sustituido). Conservar los documentos rechazados: responden a la siguiente persona que tenga la misma idea.

Resultado esperado

Quienes revisan discuten sobre el problema y las disyuntivas, no sobre la falta de contexto; el documento aceptado se convierte en referencia para la implementación y —tal como sugiere el capítulo citado de Google— en el criterio, al momento del lanzamiento, para comprobar si se alcanzaron los objetivos fijados.

Límites y base de verificación

Un documento de diseño no es una especificación; los detalles cambian durante la implementación, y el documento debería indicar qué partes son vinculantes. Para cambios pequeños, el ritual cuesta más de lo que aporta. La estructura sigue las plantillas citadas; aquí no se mide ningún efecto sobre la calidad de las decisiones.