8. Proyecto: design doc en inglés llano

Descripción

Llegamos al final del módulo, y este es el punto donde todo lo que viste deja de ser teoría. Vas a escribir un documento de diseño completo en inglés sobre un sistema real —tuyo o del ecosistema que estás estudiando— con objetivos, no-objetivos, alternativas y riesgos, más un ADR que registre la decisión central y el README del repositorio asociado. No es un ejercicio para entregar y olvidar: es una pieza que puedes poner en tu portafolio, enlazar en tu perfil, o mostrar en una entrevista cuando alguien te pida "cuéntame de algo que hayas diseñado".

Sé lo que quizás estás pensando: "mi inglés escrito no da para un documento de diseño". Aquí está la buena noticia, y es el corazón de este proyecto. El inglés llano —el que enseñó este módulo— favorece a quien no es nativo. Las frases cortas se escriben con menos errores. El vocabulario común se equivoca menos que el rebuscado. Un native speaker que escribe "we should leverage this to facilitate the utilization of..." está escribiendo peor que tú cuando escribes "we use this to...". El criterio con el que se mide este proyecto no es tu gramática: es si un lector externo entiende el problema. Y eso sí lo puedes lograr hoy.

Conexión con el módulo: las siete lecciones anteriores fueron piezas sueltas —por qué gana el lenguaje llano, la anatomía del design doc, cómo explicar arquitectura, el ADR, el README, y el postmortem sin culpa. Esta lección las junta en un solo entregable y le pone una puerta de calidad medible: la prueba del lector externo. El postmortem de la lección 7 queda fuera del entregable a propósito —ese se escribe cuando algo falla, no cuando algo se diseña—; aquí el foco es la escritura que antecede a construir, no la que sigue a un incidente. Es también la última lección antes de que el guía pase al inglés hablado, y no es casualidad: en una reunión de diseño o en un panel de entrevista vas a explicar en voz alta exactamente este documento. Tenerlo escrito y ordenado es lo que te salva cuando el idioma se pone caro.

Qué vas a entregar

El proyecto son tres artefactos, no uno. Cada uno cumple una función distinta y juntos cuentan la historia completa de una decisión de ingeniería.

La regla que los une: el mismo problema, contado tres veces con tres niveles de detalle. El design doc lo explora, el ADR lo congela en una decisión, el README te dice cómo correr el resultado. Si los tres no hablan del mismo sistema, algo está mal.

Qué esperar de tiempo: un primer borrador serio te va a tomar entre 3 y 5 horas repartidas en dos sesiones. No lo hagas de una sentada. Escribe el design doc, duerme, y al día siguiente lo relees con ojos de lector externo antes de sacar el ADR y el README. El borrador que escribes cansado es el que suena rebuscado.

Paso 1: elige el sistema (y hazlo pequeño)

El error número uno de este proyecto es elegir un sistema demasiado grande. "Diseñar Netflix" no cabe en tres páginas y te va a hundir. Lo que buscas es un sistema con exactamente una decisión interesante que puedas defender.

Buenos candidatos:

• Un componente que ya construiste en otra guía o bootcamp (un pipeline de datos, una API, un cache).
• Una parte de un proyecto real de tu trabajo, anonimizada.
• Un rediseño honesto: "tengo esto funcionando de forma X, quiero justificar por qué lo movería a Y".

La prueba de tamaño correcto: debes poder nombrar la alternativa que descartaste en una sola frase. Si no hay una alternativa clara, no hay decisión que documentar, y sin decisión el design doc no tiene columna vertebral.

Ejemplo de sistema del tamaño justo, escrito como lo pondrías al inicio del doc:

"A background job that ingests daily CSV exports from a partner, validates them, and loads them into our reporting database. Today it runs as a single script triggered by cron; this doc proposes moving it to a queue-based worker."

Ahí ya está todo: qué hace, cómo está hoy, y qué propones cambiar. Una alternativa clarísima (cron script vs. queue worker). Eso cabe en tres páginas y se puede defender.

Paso 2: el design doc, sección por sección

Usa esta estructura. Los títulos van en inglés porque es como los verás en cualquier equipo real. Debajo de cada uno te doy una plantilla en inglés para que arranques sin mirar la página en blanco.

Title, author, status

# Design: Queue-based CSV ingestion
Author: <your name> · Date: 2026-07-19 · Status: Draft

El Status es un campo vivo: Draft → In review → Accepted → Implemented. Nunca borres uno viejo; táchalo o muévelo.

Context / Background

Aquí explicas el problema antes de proponer nada. Un lector que no estuvo en la conversación tiene que entender por qué esto existe.

Plantilla en inglés:

"Today, X works like this: ... This causes the following problem: ... We need to change it because ..."

Regla de oro: si tu sección de contexto no menciona un dolor concreto (algo se cae, algo es lento, algo cuesta caro, alguien pierde tiempo), no tienes un problema, tienes un capricho. Nómbralo.

Goals (objetivos)

Lista corta, con verbos concretos y, cuando puedas, un número.

Goals:
- Process a failed file without losing the whole batch.
- Retry a failed load automatically up to 3 times.
- Keep total ingestion time under 10 minutes for a 1 GB file.

Non-goals (no-objetivos)

Esta es la sección que separa a un junior de alguien senior, y casi nadie la escribe. Los no-objetivos dicen explícitamente qué no vas a resolver, para que nadie asuma que lo cubriste. Te protegen a ti y aclaran el alcance.

Non-goals:
- Real-time ingestion. This design stays batch/daily.
- Changing the partner's file format. We take the CSV as given.
- Historical backfill of old files. Out of scope for this doc.

Qué esperar: cuando alguien revise tu doc, la mitad de las preguntas incómodas ("¿y qué pasa con X?") desaparecen si X está listado como non-goal. Escribir tres no-objetivos honestos vale más que una página de explicaciones.

Design / Proposed solution

Aquí describes la solución. Frases cortas, un párrafo por pieza. Si necesitas un diagrama, un diagrama ASCII o una lista de pasos numerada vale más que un dibujo bonito que no puedes editar.

"A worker pulls file names from a queue. For each file, it: (1) validates the header, (2) loads rows in batches of 500, (3) marks the file as done or failed. Failed files go back to a retry queue with a delay."

Alternatives considered

El pilar del documento. Por cada alternativa: qué era, y por qué no la elegiste. Sin el "por qué no", no es una alternativa, es un adorno.

Alternatives considered:

1. Keep the single cron script.
   Rejected: one bad row fails the whole file, and we cannot retry
   without re-running everything by hand.

2. Use a managed ETL service (e.g. a hosted pipeline tool).
   Rejected: adds a paid dependency and a vendor lock-in for a job
   that runs once a day. Too much for the size of the problem.

Risks and mitigations

Todo diseño tiene filos. Nombrarlos te hace ver más senior, no menos. Por cada riesgo, una mitigación.

Risks:
- The queue could pile up if the worker crashes.
  Mitigation: alert when queue depth > 100.
- A malformed file could poison the retry queue forever.
  Mitigation: move to a dead-letter queue after 3 failed retries.

Open questions

Lo que todavía no sabes. Escribirlo no es debilidad; es honestidad, y le da al revisor un lugar exacto donde ayudarte.

"Open question: should the retry delay be fixed (5 min) or exponential? Leaning fixed for simplicity — feedback welcome."

Paso 3: el ADR de la decisión central

El design doc explora. El ADR congela. Del documento entero sale una sola decisión que merece quedar registrada para siempre, y esa va en un Architecture Decision Record con el formato clásico de cuatro campos.

# ADR 001: Use a queue-based worker for CSV ingestion

## Status
Accepted

## Context
The cron script fails the whole file on a single bad row and cannot
retry without manual re-runs. As volume grows, manual recovery does
not scale.

## Decision
We will process files through a queue-based worker. Each file is a
message; failures go to a retry queue, then to a dead-letter queue
after 3 attempts.

## Consequences
Positive: partial failures no longer block the batch; retries are
automatic; the worker scales horizontally.
Negative: we add a queue as new infrastructure to run and monitor.

Tres cosas que distinguen un ADR de un design doc, y que conviene tener claras porque se confunden todo el tiempo:

• El ADR es inmutable. No lo editas cuando cambias de opinión: escribes un ADR nuevo que dice "supersedes ADR 001" y marcas el viejo como Superseded. El historial de decisiones es el valor.
• El ADR no argumenta, declara. El "por qué" completo vive en el design doc; el ADR guarda el resumen que un mantenedor futuro necesita en 30 segundos.
• Consequences incluye lo negativo. Un ADR que solo lista ventajas miente. La sección negativa es la que te creerá el lector.

Paso 4: el README del repositorio

El README es lo primero que ve alguien que llega a tu código, y muchas veces lo único. Su trabajo es que un desconocido pase de "no sé qué es esto" a "lo tengo corriendo" sin preguntarte nada.

Esqueleto en inglés, en el orden que la gente realmente lee:

# CSV Ingestion Worker

One line: what it does and who it is for.
> Ingests daily partner CSVs into the reporting database, with retries.

## Why it exists
Two sentences on the problem. Link to the design doc.

## Requirements
- Python 3.12+
- A running queue (see config below)

## Quickstart
    git clone <repo>
    make install
    make run

## Configuration
| Env var        | What it does                 | Default |
|----------------|------------------------------|---------|
| QUEUE_URL      | Where to read file names     | —       |
| MAX_RETRIES    | Attempts before dead-letter  | 3       |

## Links
- Design doc: ./docs/design.md
- Decision record: ./docs/adr/001-queue-worker.md

La regla del README: el Quickstart va arriba, no abajo. Quien llega quiere correrlo, no leer tu filosofía. Y el bloque de comandos debe funcionar copiado tal cual; un comando que falla en la primera línea destruye toda la confianza en el resto del documento.

Paso 5: autorrevisión con la rúbrica de lenguaje llano

Antes de mostrárselo a nadie, pasa tu propio texto por la rúbrica del módulo. Esto es lo que más te va a subir la calidad y, paradójicamente, lo que más tranquiliza si sientes que tu inglés no alcanza: casi todo consiste en quitar, no en escribir mejor.

Tabla de reemplazos. Busca la columna izquierda en tu texto y cámbiala por la derecha:

Checklist de autorrevisión. Léelo con el dedo sobre cada punto:

• Frases largas partidas. Si una frase pasa de dos líneas o tiene tres comas, córtala en dos. Punto es tu mejor amigo y el que menos errores de gramática te deja cometer.
• Voz activa. "The worker loads the rows" le gana a "the rows are loaded by the worker". La activa es más corta y más clara, y a un no nativo se le equivoca menos.
• Un acrónimo, una definición. La primera vez que aparece DLQ, escribe "dead-letter queue (DLQ)". Después usa DLQ.
• Cada alternativa tiene su "why not". Si una está sin rechazo explícito, o la justificas o la borras.
• Los no-objetivos existen. Al menos dos. Si no encuentras ninguno, no pensaste bien el alcance.
• Cero adjetivos de humo. robust, seamless, powerful, cutting-edge. No prueban nada y suenan a folleto. Bórralos.

Qué esperar: al aplicar la tabla y el checklist, tu documento va a encoger entre un 15 % y un 30 %. Eso es éxito, no pérdida. El texto que queda es más fácil de leer y, para ti, más fácil de haber escrito bien.

Paso 6: la prueba del lector externo (el criterio de aceptación)

Aquí está la puerta de calidad del proyecto, y es la única nota que importa. Tu documento no se evalúa por tu gramática ni por tu vocabulario. Se evalúa por comprensión ajena. El criterio es concreto:

Alguien que no conoce tu proyecto debe poder explicar, con sus propias palabras: (1) qué problema resuelve, (2) qué alternativa descartaste, y (3) por qué.

Cómo correr la prueba:

1. Dale tu design doc a alguien —un colega, un amigo del bootcamp, incluso alguien de otra área. No hace falta que sea nativo de inglés ni experto en tu dominio.

2. No le expliques nada de viva voz. El punto es que el documento hable solo. Si tienes que aclarar algo hablando, ese algo le falta al documento.

3. Después de leer, hazle exactamente estas tres preguntas:

   • "In your own words, what problem does this solve?"
   • "Which alternative did I reject?"
   • "Why did I reject it?"

4. Si las contesta bien, pasaste. Si titubea en alguna, no discutas: esa sección está floja. Vuelve al documento y arréglala. El lector nunca se equivoca; el documento es el que no fue claro.

Un truco si no tienes a nadie a la mano ahora mismo: léelo tú en voz alta, en inglés, como si se lo explicaras a alguien. Este es además el ensayo perfecto para el inglés hablado que viene en el próximo módulo. Los lugares donde tu propia voz tropieza o se enreda son casi siempre los lugares donde el texto está enredado. Marca esas frases y reescríbelas más cortas.

Errores comunes (y cómo evitarlos)

Ejercicios

Estos ejercicios te hacen operar las piezas del proyecto por separado —acotar un sistema, escribir non-goals, aplicar la tabla de lenguaje llano, diseñar la prueba del lector externo— antes de que las juntes las tres en tu propio design doc. Resuelve cada uno con lápiz antes de abrir la solución.

Ejercicio 1 — Encuentra la alternativa en una frase

Tienes este sistema en mente: "Quiero rediseñar cómo mi equipo despliega el backend." Es demasiado grande para un design doc de 1–3 páginas. Recórtalo hasta un sistema con exactamente una decisión defendible, y escribe la alternativa que resumiría el cambio en el formato "X vs. Y".

Ejercicio 2 — Escribe los non-goals

Sistema: un worker que sincroniza el inventario de una tienda online cada 15 minutos leyendo un CSV que sube un proveedor. Escribe al menos dos non-goals honestos para este diseño, en inglés, siguiendo el formato de la lección.

Non-goals:
- Real-time inventory sync. This design stays on a 15-minute schedule.
- Validating the CSV's business logic (e.g. duplicate SKUs across
  files). We only validate structure, not content correctness.

Ejercicio 3 — Aplica la tabla de reemplazos

Reescribe este párrafo usando la tabla de lenguaje llano de la lección:

"In order to facilitate the utilization of the new pipeline, it is recommended that you leverage the existing configuration prior to making any changes, due to the fact that a large number of services depend on it."

Ejercicio 4 — Diseña la prueba del lector externo

Escribiste el design doc del ejemplo de la lección (mover de "cron script" a "queue-based worker"). Escribe las tres preguntas exactas que le harías a tu lector de prueba, y describe una respuesta que te diría que la sección "Alternatives considered" está floja.

Entrega y cierre del módulo

Tu entregable final es una carpeta con tres archivos:

/design.md          -> el design doc completo
/adr/001-<slug>.md  -> el ADR de la decisión central
/README.md          -> el README del repositorio

Y una condición: que una persona ajena haya pasado la prueba del lector externo respondiendo las tres preguntas. Anota en una línea al final del design doc quién lo leyó y qué respondió; esa nota es tu evidencia de que el documento funciona, no solo de que existe.

Con esto cierras el módulo de escritura técnica. Vale la pena decir en voz alta lo que acabas de lograr, porque es más grande de lo que parece: produjiste, en inglés, la evidencia de seniority más difícil de fingir y que no necesita el permiso de nadie. No demostraste que ejecutas tareas —eso lo hace cualquiera—; demostraste que puedes sostener una decisión por escrito frente a lectores que no estuvieron en la sala. Esa es exactamente la señal que buscan las vacantes que en la auditoría pedían "comunicación escrita de arquitectura" y "documento de diseño en lenguaje llano".

Y si el síndrome del impostor lingüístico todavía te ronda, quédate con esto: el documento que escribiste no ganó por tu inglés, ganó a pesar de que tu inglés no es perfecto —porque el lenguaje llano no premia al que sabe más palabras, premia al que se hace entender. Esa cancha está nivelada para ti. En el próximo módulo vas a tomar exactamente este documento y aprender a defenderlo hablando; llegas con la parte difícil —tener algo claro que decir— ya resuelta.

Resumen y siguiente paso

En esta lección uniste las siete lecciones anteriores del módulo en un solo entregable con tres artefactos —design doc, ADR y README— que cuentan la misma decisión de ingeniería a tres niveles de detalle, y le pusiste una puerta de calidad medible: la prueba del lector externo.

Antes de avanzar al siguiente módulo deberías poder:

• Acotar un sistema hasta que quepa en 1–3 páginas y nombrar, en una frase, la alternativa que descartaste.
• Escribir las secciones del design doc en inglés llano, con al menos dos non-goals honestos y cada alternativa con su "why not".
• Redactar un ADR de cuatro campos que declare la decisión sin argumentarla, incluyendo una consecuencia negativa real.
• Escribir un README con el Quickstart arriba y comandos que funcionan copiados tal cual.
• Pasar tu propio texto por la tabla de reemplazos y el checklist de lenguaje llano, y ver el documento encoger sin perder significado.
• Correr la prueba del lector externo con una persona real y registrar su respuesta a las tres preguntas.

Si alguno de estos puntos todavía te cuesta, vuelve al paso correspondiente antes de cerrar el módulo: el documento que sale de aquí es el que vas a defender hablando en el módulo siguiente, y una grieta escrita se nota todavía más en voz alta.

El puente: en el módulo 5 —inglés hablado— vas a tomar exactamente este design doc y aprender a explicarlo en una reunión de diseño y a defenderlo frente a preguntas en vivo, sin la red de poder borrar y corregir que tuviste aquí. Llegas con la parte más difícil ya resuelta: tener algo claro que decir. Lo que sigue es aprender a decirlo.

Recursos

• Design Docs at Google — el artículo de referencia sobre cómo Google usa los design docs antes de escribir código; su anatomía por secciones (context, goals, non-goals, alternatives) es la misma que sigue esta lección.
• Architecture Decision Records (adr.github.io) — el sitio de la comunidad ADR, con plantillas y herramientas para escribir y organizar tus propios registros de decisión.
• Documenting Architecture Decisions — Michael Nygard — el post original que propuso el formato de cuatro campos (Status, Context, Decision, Consequences) que usa el ADR de esta lección.
• Make a README — guía práctica sobre qué debe llevar un README y en qué orden, con el mismo criterio de "que alguien pueda correrlo sin preguntarte nada".
• Plain Language Guidelines (digital.gov) — las guías oficiales del gobierno de Estados Unidos sobre escritura en lenguaje llano; la base detrás de la tabla de reemplazos y el checklist de autorrevisión de esta lección.