Escribir un design doc o RFC en inglés
Un design doc se escribe para que alguien te diga que estás equivocado antes de que escribas el código. Eso define su estructura: el problema primero, las alternativas en serio, y la decisión al final.
El design doc es el texto que más pesa en la carrera de alguien que trabaja para afuera: es lo que leen personas que nunca te vieron trabajar, y por lo que deciden si te dan un problema más grande.
Y es el que más fácil sale mal, porque la tentación es escribir la solución que ya tenés en la cabeza y buscarle argumentos. Un design doc bien escrito hace lo contrario: plantea el problema con tanta claridad que las alternativas se pueden comparar de verdad, incluida la de no hacer nada.
La estructura
Plantilla
Design doc / RFC
Context and problem
What is happening today, with evidence: "Exports over 10k rows time out. This affected 14 customers last month and generated 31 support tickets."
Con números y sin la solución adentro. Si el problema se enuncia como «necesitamos una cola de mensajes», la decisión ya está tomada y el documento no sirve para decidir.
Goals / Non-goals
Goals: exports of any size complete reliably. Non-goals: changing the export file format, supporting scheduled exports.
Los non-goals son la sección más útil y la que casi nadie escribe: son los que frenan la discusión que no corresponde a este documento.
Proposal
The approach, in enough detail to be argued with: data flow, components, contracts, and what changes for the user.
Suficiente detalle para estar en desacuerdo. Un diagrama y las dos o tres decisiones que lo sostienen.
Alternatives considered
Each one with why it was not chosen: "Streaming the CSV directly: simpler, but keeps a connection open for minutes and does not survive a deploy."
En serio, no de adorno. Si las alternativas están escritas para perder, cualquier lector con experiencia lo nota y deja de confiar en el resto.
Trade-offs and risks
What gets worse: "This adds a queue to a system that had none, so we now need to monitor it and handle poison messages."
Escribir el costo de tu propia propuesta es lo que hace que te crean el beneficio.
Rollout plan
How it ships: behind a flag, for internal accounts first, with a way back.
Cómo se prueba en producción sin romper a nadie, y cómo se vuelve atrás si sale mal.
Open questions
What you want input on: "Should exports expire after 7 days, or stay until the customer deletes them?"
Dirige la revisión a donde te sirve. Sin esta sección, los comentarios van a caer en la parte que más fácil es opinar, que casi nunca es la importante.
Antes de seguir, predecí
El lenguaje de las decisiones
El inglés de un design doc es formal pero directo, y tiene fórmulas fijas para lo que más cuesta decir: proponer con firmeza sin sonar cerrado, y descartar una opción sin despreciarla.
| Intención | Fórmula | Nota |
|---|---|---|
| Proponer | I propose we … / This document proposes … | Directo; «maybe we could» debilita el documento entero |
| Justificar una decisión | We chose X over Y because … | Siempre «because»: una decisión sin porqué se vuelve a discutir en seis meses |
| Descartar una alternativa con respeto | X is a reasonable option, but it doesn't handle … | Reconocer lo bueno de lo que descartás es lo que hace creíble el descarte |
| Marcar un supuesto | This assumes exports stay under 1M rows. If that changes, … | Los supuestos explícitos son lo que permite revisar la decisión después |
| Reconocer un costo | The main trade-off is … | Escribirlo vos es mejor que que lo encuentre el revisor |
| Dejar algo abierto | Open question: … I'd like input from @team-platform | Con destinatario; una pregunta sin dueño no la contesta nadie |
| Cerrar el alcance | Out of scope for this document: … | Es el non-goal aplicado a la discusión |
| Pedir revisión | Looking for feedback by Thursday; I'll start on the API contract after that | Fecha y qué pasa si no hay comentarios: sin eso el documento queda en revisión para siempre |
| Escrito así | Cómo se lee | Mejor |
|---|---|---|
| We need a message queue | La solución disfrazada de problema | Exports over 10k rows time out, affecting 14 customers last month |
| This is obviously the best approach | Cierra la discusión que el documento vino a abrir | This approach fits best given our current traffic; the main trade-off is … |
| Alternative: do nothing (bad) | Alternativa de adorno | Alternative: do nothing. The 31 monthly tickets are manageable today, but the largest accounts are growing |
| We could maybe try to consider using a queue | Nadie sabe qué se está proponiendo | I propose we move exports to a background queue |
| This will scale | Promesa sin número | This handles 50 concurrent exports of 1M rows each; beyond that we would need … |
Practicalo
Reescribilo
El arranque de un design doc que empieza por la solución y no deja nada para discutir. Reescribilo para que abra con el problema y sus números, y deje las alternativas realmente abiertas.
# Adding Kafka
We need Kafka because our system is not scalable and everyone uses Kafka nowadays. It is obviously the best option. I looked at other things but they are not good. Let me know if you agree so I can start.# Making large exports reliable ## Context and problem Exports over 10k rows time out at 30s. Last month this affected 14 customers and generated 31 support tickets. The three largest accounts are growing ~20% per quarter, so the threshold gets hit more often each month. ## Goals - Exports of any size complete, or fail with a clear reason. - A failed export can be retried without losing work. ## Non-goals - Changing the CSV format. - Scheduled or recurring exports. ## Proposal Move exports to a background job queue. The request returns a job id immediately, and the file is fetched when ready. ## Alternatives considered - **Do nothing.** 31 tickets a month is manageable today, but the trend makes this worse every quarter. - **Raise the timeout.** Cheapest option, and it buys maybe two quarters. It does not survive a deploy mid-export. - **Stream the response directly.** Simpler, no new infrastructure, but it holds a connection open for minutes and cannot be retried. ## Trade-offs This adds a queue to a system that has none: one more thing to monitor, and we need a story for stuck and repeatedly failing jobs. Looking for feedback by Thursday. If there are no objections, I'll start with the job contract.
El título dice el problema, no la tecnología. Hay números, non-goals, tres alternativas con su argumento —incluida no hacer nada— y el costo de la propuesta escrito por quien la propone. Y tiene fecha de cierre.
# Making large exports reliable Exports over 10k rows time out (14 customers, 31 tickets last month). I propose moving them to a background queue: the request returns a job id and the file is fetched when ready. Alternatives: raising the timeout buys two quarters and dies on deploys; streaming cannot be retried; doing nothing gets worse ~20% per quarter. Trade-off: a queue is new infrastructure to monitor. Open question: should finished exports expire after 7 days? Feedback by Thursday, please.
La versión de una pantalla, para un cambio de tamaño mediano. Tiene las mismas partes: problema con números, propuesta, alternativas, costo, pregunta abierta y fecha. Largo y completo no son lo mismo.
Fijate qué cambió primero: el título. «Adding Kafka» sólo se puede aprobar o rechazar; «Making large exports reliable» se puede discutir.
trade-off
/ˈtreɪdɒf/ · suena como tréidof
Error común: decir «tradeóf», separando y acentuando mal
scope
/skəʊp/ · suena como skóup
Error común: decir «escop», con e inicial
queue
/kjuː/ · suena como kiú, una sola sílaba
Error común: decir «kueue» o «cué»
throughput
/ˈθruːpʊt/ · suena como zrúput, con z de «think»
Error común: decir «zroughput» pronunciando la gh
rationale
/ˌræʃəˈnɑːl/ · suena como rashonáal
Error común: decir «rasional» como en español
El audio lo genera tu navegador con voz sintetizada: alcanza para orientarse, y una persona que habla inglés lo dice mejor.
En la práctica
Cierre
Autoevaluación
¿Lo entendiste?
Práctica