jonshaw199/decision-doc-quality

Calidad de Documentos de Decisión / Opciones

Usa estas reglas para cada decisión de ingeniería, spike o documento de opciones que proponga alternativas y una recomendación. El lector es un compañero ocupado sin contexto; el documento debe ser escaneable, claro y verificable.

Audiencia: asume contexto cero

• Asume que el lector no conoce ninguno de los conocimientos tribales. Explica o hipervincula cada término, acrónimo, nombre de servicio, herramienta y patrón de uso (p.ej., CDC, Debezium, Kafka, SNS, SQS, outbox, replicación lógica, Temporal). "Nadie sabe qué significa nada de esto."
• Explica qué es y qué hace una cosa en palabras sencillas antes de basarte en ella. Prefiere una frase sencilla acompañada de un enlace en lugar de solo jerga.
• No agregues una sección separada de glosario a menos que se solicite; enlaza los términos en línea.

Estilo de escritura

• Encabeza con el punto (BLUF). Declara la conclusión principal primero, luego los detalles.
• Corto. Las frases de una línea son mejores que los párrafos. Si una sección parece un muro de texto, córtala. Nadie lee documentos largos.
• Lenguaje sencillo. Nada de basura de IA, sin relleno que "suene bien", sin narración de la evolución del propio documento, sin defender tu razonamiento dentro del documento (p.ej., nunca "evidencia directa, no teoría").
• Sin guiones largos en ninguna parte. Sin énfasis en MAYÚSCULAS (usa negrita). Sin numeración decorativa ni separadores de punto medio que parezcan generados por máquina.
• "Nosotros" para el trabajo que el equipo haría; "Yo" para la opinión/inclinación del autor. Manténlos separados.

Estructura

• Recomendación / TL;DR al principio. Pocas líneas: la inclinación, las razones clave (como viñetas), enmarcado como una primera impresión de un documento vivo que cambiará después de la opinión del equipo. Explicita la indiferencia y flexibilidad cuando sean reales; aún así indica una preferencia y por qué.
• Un bloque colapsable (toggle) por opción. La línea colapsada muestra una etiqueta corta y una esencia de una línea en lenguaje sencillo. Dentro: un diagrama simple, Cómo funciona, qué se reutiliza (con enlaces de prueba), qué es completamente nuevo, escala/compensación, y un pequeño esbozo de código o configuración. Mantén la superficie escaneable.
• Mantén las secciones pares paralelas (la consistencia no es opcional). Las opciones/herramientas/candidatos son hermanos, por lo que TODOS DEBEN seguir la misma plantilla: los mismos encabezados de subsección en el mismo orden, la misma presencia de diagrama / medio / esbozo de código, la misma profundidad. Fija la plantilla una vez (desde la sección más fuerte) y aplícala a todas; cuando agregues o edites una sección, realinea las demás. Nunca dejes que cada sección derive en su propia forma, una estructura divergente se lee como descuidada y anula todo el propósito (comparación fácil lado a lado). Este es un modo de fallo recurrente: verifícalo antes de compartir.
• Agrupa las opciones por un único eje limpio (p.ej., cuándo sucede algo, o cómo). Nunca mezcles dos ejes en una misma agrupación ni crees categorías de pares falsos que se superpongan. Si algo es un detalle de implementación de otra opción (un ejecutor, una ubicación de destino), intégralo, no lo listes como un par.
• Ilustra el núcleo compartido/más difícil, no solo las opciones, con su propio esbozo (maneja el ciclo de vida completo, p.ej., crear/actualizar y eliminar).
• Diagramas (mermaid) para ilustración; manténlos precisos (no dibujes una tabla como una base de datos separada, etc.).
• Termina con una invitación a recibir comentarios ("¿Otras ideas?"); nunca termines abruptamente.
• Mantén los metadatos al mínimo, solo lo que se desea (a menudo solo el enlace al ticket). Elimina líneas de estado/plantilla que no le importen al autor.

Exhaustividad de opciones

• Enumera las opciones exhaustivamente, no solo las dos o tres habituales. Los problemas reales tienen muchas; incluye también las claramente malas para que todo el campo sea visible (etiquétalas como débiles/línea base).
• Reconoce siempre la línea base de "no hacer nada" y declara su consecuencia.
• Investiga fuentes reales (documentación, Stack Overflow, Reddit, referencias de proveedores/patrones) para encontrar opciones y la terminología correcta. Wikipedia sola es el defecto perezoso; encuentra la fuente primaria relevante.
• Nombra correctamente los patrones de diseño establecidos y enlácelos; no apliques incorrectamente un nombre de patrón. Verifica que el patrón realmente encaje antes de citarlo.

Evidencia (la regla central)

• Cada afirmación sobre lo que el sistema ya tiene está respaldada por un hipervínculo a la prueba (archivo fuente + línea, configuración de infraestructura, ticket). Sin suposiciones, sin evasivas.
• Si una afirmación no se puede probar con un enlace, márcala como no verificada en lugar de declararla como un hecho.
• Verifica leyendo el archivo/infraestructura real. No afirmes el hallazgo de un subagente como un hecho sin leerlo; distingue "lo leí" de "un agente lo informó", y declara la confianza cuando sea importante.
• Nunca cambies de opinión en silencio. Cuando una comprobación cambie una afirmación anterior, di qué estaba mal y por qué, y corrígelo.
• Desafía la premisa y tus propias conclusiones cuando te presionen; vuelve a verificar en lugar de defenderte.
• Hipervincula cada identificador, nombre de archivo, ticket, PR y referencia; nunca dejes un ID desnudo para que el lector lo busque.

Contenido del documento de opciones

• Separa el núcleo compartido difícil (el trabajo necesario sin importar la opción) de los envoltorios/mecanismos a su alrededor, y di cuál es el esfuerzo y riesgo reales.
• Da pros y contras, fundamentados. No hagas afirmaciones exageradas ("la mayor parte del trabajo y casi todo el riesgo" → suaviza a lo preciso).
• Anota qué reutiliza cada opción (que ya existe) frente a lo que es completamente nuevo.

Proceso

• Haz ediciones mínimas y dirigidas. No reescribas todo el documento para un cambio pequeño.
• Para redacción delicada, muestra el borrador en el chat e itera antes de aplicar.
• Para un mensaje de revisión/Slack adjunto: mantenlo increíblemente corto y genuinamente acogedor (la gente está ocupada y no querrá leerlo); no digas que es urgente o no urgente a menos que te lo pregunten; prepara a los revisores con el marco más útil.

Verificación final

Antes de compartir un documento, verifica:

• El punto principal / recomendación está al principio y es corto.
• Cada afirmación de "lo que tenemos" tiene un enlace de prueba; las afirmaciones no verificadas están etiquetadas.
• La jerga está explicada o enlazada; un lector sin contexto puede seguirlo.
• Las opciones están agrupadas en un único eje limpio, cada una colapsable con un resumen de una línea en lenguaje sencillo.
• No hay guiones largos, ni énfasis en MAYÚSCULAS, ni auto-narración, ni basura de IA.
• "Nosotros" vs "Yo" se usa correctamente; la inclinación está declarada pero la flexibilidad es clara.
• El documento invita a recibir comentarios y no termina abruptamente.