Cómo redactar un documento de diseño o RFC sobre el que los revisores puedan decidir

Objetivo

Conseguir que las personas que tendrán que convivir con un cambio importante decidan sobre él a partir de un único documento que puedan leer en veinte minutos, antes de que nadie escriba el código. Más adelante, el documento sirve como registro de por qué el sistema es como es.

Requisitos previos

Un cambio demasiado grande o demasiado controvertido para la descripción de un pull request; un grupo conocido de revisores con autoridad para aceptarlo; un lugar donde el documento viva junto al código (un directorio docs/rfcs/, un archivo numerado, un pull request). PEP 1 (citado) y la plantilla de RFC de Rust (citada) son ejemplos públicos de este tipo de procesos; las plantillas de documentos de diseño de Google (citadas) exigen a los autores tener en cuenta la seguridad, la internacionalización, el almacenamiento y la privacidad, y en la mayoría de los casos esas partes las revisan expertos en cada ámbito.

Pasos

1. Escribe el planteamiento del problema antes de cualquier propuesta: quién se ve afectado, qué ocurre hoy y qué restricción obliga a cambiar. Si el problema no se puede exponer en un párrafo, el documento aún no está listo.
2. Enumera los objetivos como enunciados numerados y comprobables, y define no objetivos que delimiten el alcance. Los no objetivos evitan que la revisión se extienda a deseos colaterales.
3. Explica la propuesta dos veces, como hace la plantilla de Rust: primero una explicación a nivel de guía, que muestre cómo percibe el cambio un usuario, y después una explicación a nivel de referencia, con semántica, formatos y casos límite precisos.
4. Registra las alternativas consideradas y por qué se rechazó cada una. PEP 1 pide incluir las ideas rechazadas junto con su razonamiento, para no repetir la discusión; la plantilla de Rust tiene una sección de justificación y alternativas con el mismo fin.
5. Expón con honestidad los inconvenientes, los efectos sobre la compatibilidad, la migración y el despliegue, y el coste operativo; un documento sin inconvenientes parece propaganda.
6. Termina con las preguntas sin resolver, divididas entre «deben decidirse en esta revisión» y «pueden resolverse durante la implementación».
7. Distribuye el documento con una fecha límite de revisión, responde a los comentarios en el propio documento y no en el chat, y registra el resultado en una línea de estado (borrador, aceptado, rechazado, reemplazado). Conserva los documentos rechazados: responden a la siguiente persona que tenga la misma idea.

Resultado esperado

Los revisores discuten sobre el problema y las contrapartidas, no sobre contexto que falta; el documento aceptado se convierte en la referencia para la implementación y, como sugiere el capítulo citado de Google, en una medida para comprobar en el lanzamiento si se cumplieron los objetivos planteados.

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 debe indicar qué partes son vinculantes. En cambios pequeños, el trámite cuesta más de lo que aporta. La estructura sigue las plantillas citadas; aquí no se ha medido ningún efecto sobre la calidad de las decisiones.