Inglés para developers: escritura técnica
Cómo escribir un design doc en inglés: estructura, frases y cómo sonar seguro
21 de octubre de 2026
La estructura que necesita todo design doc, más las frases exactas para goals, non-goals, alternativas consideradas, preguntas abiertas y pedir sign-off.
La estructura de un design doc
La mayoría de los equipos esperan más o menos la misma forma: un problem statement, goals y non-goals, la solución propuesta, alternativas consideradas, preguntas abiertas y un plan de rollout. Tener la estructura correcta importa, pero es la frase exacta en inglés dentro de cada sección la que decide si los reviewers discuten el contenido de tu propuesta o se quedan discutiendo la redacción.
La trampa más grande es el registro: si hay demasiado hedging, tu propuesta suena como ruido sin confianza; si suena demasiado seguro, cierras la revisión que en realidad necesitas. Esta guía te da las frases exactas para cada sección, y la calibración entre los dos extremos.
Puntos clave
- Un goal necesita un número. 'Make it fast' no es verificable; 'p99 latency under 200ms' sí lo es.
- Escribe los non-goals explícitamente. Un non-goal que no se escribe se convierte en una discusión que descarrila todo más adelante.
- Para cada alternativa, da el tradeoff y la razón específica por la que la descartaste, no solo la opción que elegiste.
- Una pregunta abierta necesita una inclinación y un responsable asignado. Un 'not sure about this' sin dirección suena a falta de preparación.
- Pide sign-off con una fecha límite y un resultado por defecto, para que el documento no quede en el limbo de la revisión.
Las secciones, en orden
- 1
Problem statement
Qué está roto o falta hoy, en uno o dos párrafos. Todavía sin solución.
- 2
Goals
Resultados verificables que el diseño debe lograr.
- 3
Non-goals
Qué queda explícitamente fuera del alcance de este documento.
- 4
Proposed solution
El diseño en sí, con diagramas si ayuda.
- 5
Alternatives considered
Qué más evaluaste, y por qué no lo elegiste.
- 6
Open questions
Qué queda sin resolver, dirigido a un equipo o persona específica cuando sea posible.
- 7
Rollout plan
Cómo se lanza esto: fases, feature flags, plan de rollback.
1. Writing clear goals and non-goals
1. Escribir goals y non-goals claros
Un goal sin número no es un goal. Un non-goal que nunca se escribe se convierte en una discusión en los comentarios tres semanas después.
“The goal of this document is to propose a solution for the checkout timeout issue.”
Abre el documento declarando el objetivo directamente. No lo entierres bajo tres párrafos de contexto.
“This system must support 10,000 writes per second with p99 latency under 200ms.”
Un goal debe ser verificable. 'Make it fast' no es un goal. Un número sí lo es.
“This document does not address the migration of existing data. That will be covered in a separate RFC.”
Un non-goal explícito evita que los reviewers desvíen la discusión hacia temas que no corresponden.
“We are explicitly not solving the multi-region case in this iteration.”
Frena el scope creep en los comentarios antes de que empiece.
2. Describing alternatives considered
2. Describir las alternativas consideradas
La plantilla es siempre la misma: qué consideraste, el tradeoff, y la razón específica por la que lo descartaste. Nunca presentes solo la opción que elegiste.
“We considered caching at the application layer, but rejected it because it would not survive a service restart.”
La plantilla para cada alternativa: qué consideraste, y la razón específica por la que la descartaste.
“Option A is faster to ship but harder to maintain long-term. Option B is the opposite. We are choosing B because maintainability is our priority this quarter.”
Presenta ambas opciones de forma equilibrada antes de anunciar tu elección. Así suena a decisión, no a defensa.
“This approach trades some write latency for much simpler failure recovery.”
Nombrar el tradeoff en una sola oración es más claro que un párrafo largo justificándolo.
“An earlier draft proposed a synchronous call here. We moved away from it after load testing showed it did not hold up past 500 requests per second.”
Mostrar que consideraste y probaste una alternativa genera más credibilidad que presentar solo la respuesta final.
3. Flagging open questions
3. Señalar preguntas abiertas
Una pregunta abierta con una inclinación y un responsable asignado consigue respuesta. Un vago 'not sure about this part' no.
“Open question: should this happen synchronously or asynchronously? Leaning toward async, open to pushback in review.”
Da una dirección aunque no estés seguro. Una inclinación más una invitación a dar feedback suena seguro, no desprolijo.
“We have not yet decided on the retry strategy. Flagging this for discussion in the review.”
Nombrar una decisión pendiente explícitamente es mejor que esperar que nadie note que falta.
“This is still an open question. Feedback from the security team would be especially useful here.”
Dirigir la pregunta abierta a un equipo o persona específica hace que se resuelva más rápido que un 'feedback welcome' genérico.
4. Asking for sign-off
4. Pedir sign-off
Nombra quién debe aprobar, para cuándo, y qué pasa por defecto si nadie objeta.
“Please review by Friday. Flag any blocking concerns in the comments.”
Pedir revisión con una fecha límite clara consigue respuestas. Un 'thoughts welcome' sin fecha muchas veces no.
“I am looking for sign-off from the platform and security teams before starting implementation.”
Nombrar exactamente quién debe aprobar evita que el documento quede en el limbo sin que nadie sepa si es el bloqueante.
“If there are no blocking objections by Monday, I will consider this approved and start implementation.”
Un resultado por defecto y una fecha sacan al documento de una revisión interminable y lo convierten en una decisión.
Calibrar tu registro: ni demasiado dubitativo, ni falsamente seguro
Ni demasiado dubitativo, ni falsamente seguro
Demasiado hacia un lado
“I think maybe we could possibly try using a queue here, if that makes sense?”
Calibrado
“I propose using a queue here to decouple the two services. Open to alternatives if the latency numbers do not hold up.”
Demasiado hedging suena a falta de confianza en tu propia propuesta, aunque la idea de fondo sea sólida.
Demasiado hacia un lado
“This is definitely the only way to solve this. There is no other option.”
Calibrado
“Based on the load testing results, I believe this is the best approach. I am open to reconsidering if new constraints come up.”
Sonar falsamente seguro cierra la revisión que en realidad necesitas. Afirma tu conclusión, y después deja la puerta abierta.
Artículos relacionados
¿Listo para practicar tu inglés en el trabajo?
Lingua-e tiene ejercicios interactivos basados en conversaciones reales de developers: standups, code reviews, retrospectivas y más. Practica hasta que salga solo.
Prueba Lingua-e gratis
Escrito por
Roxana LafuenteFundadora de Lingua-e
Roxana Lafuente es ingeniera de software con más de 8 años de experiencia. Al comienzo de su carrera, aunque ya había aprobado el First Certificate in English, se bloqueaba cada vez que tenía que hablar en el standup diario. Era un problema que nadie estaba resolviendo. Después de más de 2.000 standups, descubrió qué es lo que realmente construye la fluidez: practicar situaciones que se parecen a tu trabajo real. Creó Lingua-e para que otros developers no tuvieran que tomar el camino largo para sentirse seguros trabajando en un entorno de desarrollo internacional.