Cómo escribir buenos documentos de diseño

• Un documento de diseño es un informe técnico que organiza la estrategia de implementación, las restricciones y los trade-offs de un sistema.
• El documento de diseño cumple la función de convencer al lector de que ese diseño es adecuado para la situación.
• La estructura del documento es importante, y debe evitar que el lector se sorprenda con el contenido mediante un flujo lógico.
• A través de la edición, es necesario reducir las palabras innecesarias y ahorrar los recursos de concentración del lector.
• Es importante usar párrafos cortos y apéndices, además de mejorar la capacidad de redacción de documentos mediante la práctica.

---

Definición

• Un documento de diseño es un informe técnico que organiza la estrategia de implementación del sistema en el contexto de los trade-offs y las restricciones.

Objetivo

• Así como una demostración en matemáticas convence de un teorema, el propósito de un documento de diseño es persuadir al lector de que ese diseño es el óptimo.
• Durante el proceso de diseño, el acto mismo de escribir aumenta el rigor del pensamiento.
• Al redactar un documento de diseño, se pueden convertir ideas vagas en pensamiento concreto.

Organización

• La estructura de un buen documento de diseño es tan importante como la organización del código.
• Así como los principiantes escriben código, muchas personas tienden a crear “documentos de diseño espagueti”.
• Si se enumeran oraciones sin un orden lógico, al lector le resulta difícil seguir el contexto y se confunde.
• Un documento perfecto debe tener un flujo natural para que el lector no se sorprenda, y cada oración debe continuar de forma obvia a partir de la anterior.
• El objetivo es entender el estado mental del lector y guiarlo gradualmente hacia un nuevo estado.
• Hay que resolver de antemano las objeciones previsibles y explicarlas antes de que el lector plantee una contraargumentación.

Edición

• Después de organizar bien el contenido, la etapa de eliminar palabras innecesarias (edición) es importante.
• La concentración del lector es un recurso limitado, y la información innecesaria debe eliminarse sin dudar.
• En un borrador, cerca del 30% de las expresiones sin sentido pueden reducirse.
• Al editar documentos de otras personas y desarrollar una mirada crítica, también se puede pulir la propia escritura con mayor eficiencia.
• Practicar con tuits cortos (límite de 280 caracteres) también ayuda a simplificar el pensamiento y mejorar la capacidad de condensarlo.

Experiencia y práctica

• No hay atajo mejor para mejorar que la práctica repetida.
• La experiencia con la cultura centrada en documentos en Amazon fue de gran ayuda para mejorar la capacidad de redactar documentos.
• En reuniones importantes, se distribuyen documentos de diseño de entre 1 y 6 páginas, y luego todos los leen en silencio y escriben sus comentarios en los márgenes.
• Recibir retroalimentación permite mejorar de forma real las habilidades de escritura.

Consejos concretos

Usar párrafos cortos

• Un documento de diseño debe construir su flujo con bullet points concisos y continuos.
• Cada bullet point (observación, idea, problema, mejora, etc.) debe consistir en un párrafo corto enfocado en un solo concepto.
• Cada párrafo debe tener la claridad suficiente como para poder resumirse en una sola oración, lo que ayuda a ahorrar los recursos de memoria de corto plazo del lector.

Uso de apéndices

• Los cálculos complejos o resultados de simulaciones deben organizarse en detalle en un apéndice y mencionarse en el cuerpo principal solo como una nota breve al pie.
• El apéndice no es esencial para entender las conclusiones principales del texto, y se ofrece para que los lectores interesados puedan consultarlo.

Ejemplo de edición

• (Antes de editar, párrafo verboso):

  Cada bullet point debe convertirse en un párrafo separado dentro del documento. Cada párrafo debe poder resumirse en una sola oración. No necesariamente tiene que ser literalmente una sola oración, ya que puede incluir explicaciones adicionales para desarrollar el concepto. Pero, después de leerlo, debe poder resumirse en una sola oración.

• (Después de editar, párrafo simplificado):

  Cada bullet point debe ser un párrafo que pueda resumirse en una sola oración. No hace falta que sea literalmente una sola oración, y si es necesario se puede añadir explicación complementaria. Pero al terminar de leerlo, debe poder comprimirse en una sola oración.

Cierre

• Un documento de diseño es un proceso importante en el que se puede desarrollar la capacidad mediante rigor en el pensamiento, flujo lógico, edición centrada en el lector y práctica repetida.

[GN⁺]

Comentarios de Hacker News

• El comentario comparte dos citas del artículo que le parecieron especialmente impactantes. La primera, de una captura de pantalla en X: "las ideas mejoran 10 veces durante el proceso de escribir". La segunda, al inicio: "la persona más importante a la que hay que persuadir es el propio autor". Le sorprende que, incluso después de años trabajando en la industria, todavía haya gente que se oponga a la necesidad de los documentos de diseño. Cita a Leslie Lamport: "escribir es la forma en que la naturaleza nos muestra lo desordenado que es nuestro pensamiento". Si alguien quiere mejorar más su escritura técnica, recomienda el artículo Write Like an Amazonian(https://medium.com/@apappascs/…)
  • El consejo de "convertir los adjetivos en datos" parece haberse extendido tanto por toda la industria tecnológica que ahora muchos currículums están llenos de cifras al punto de que cuesta entender qué significan
• Como revisor de diseño, hay algo que cree que toda persona que redacta documentos debe interiorizar. Es la idea de que "un buen documento permite que el lector entienda el problema y el modelo mental, de modo que cuando finalmente se presenta la solución nacida tras semanas de reflexión, la acepte de forma natural". Su cita favorita es: "si hubiera tenido más tiempo, habría escrito una carta más corta". Cree que un documento de diseño debe volver simple lo complejo, y no ser un lugar donde se vuelque sin filtro cada tropiezo y cada fracaso del desarrollador. Ese material también puede tener valor, pero conviene organizarlo en un documento aparte o en un apéndice. Lo importante es mostrar con sencillez el camino a seguir
  • Prefiere la expresión "más tiempo, carta más corta"
  • Siempre se hace estas preguntas: "¿Va a surgir una discusión innecesaria sobre este tema?", "¿vale la pena discutirlo?". Su objetivo es que una persona nueva pueda sumarse a la conversación sin dificultad y que no haya controversia sobre las partes que no son importantes
• Las reuniones en Amazon comienzan con el presentador repartiendo un documento escrito en prosa. Todos se sientan en silencio a leerlo y anotan comentarios y preguntas en los márgenes con un bolígrafo rojo. Nunca ha trabajado realmente en Amazon, pero este método le parece sorprendentemente efectivo, y a quienes hablan de esa experiencia suele encantarles. A primera vista puede parecer ineficiente gastar un tiempo valioso de reunión solo leyendo juntos, pero si la gente leyera y se preparara de antemano, las reuniones podrían ser más cortas. La lectura simultánea en tiempo real termina haciendo que todos pasen el tiempo de forma difusa, ya sea esperando a los lectores más lentos o porque no todos entienden igual por falta de contexto. Cuenta que en Google vio muchas veces revisiones de diseño donde la mayoría de los asistentes abrían el documento por primera vez y entraban a discutir sin preparación. Cree que eso pasaba porque Google no tenía una cultura fuerte de documentación y porque implícitamente se toleraba que leads y managers llegaran sin prepararse. Si se consolidara una cultura donde todos leyeran bien antes de la reunión, el tiempo de reunión podría usarse de forma mucho más eficiente
  • La gente dice que leer antes reduce el tiempo de la reunión, pero la práctica de Amazon es una respuesta a la realidad de que la gente en verdad no lee antes. En un artículo anterior sobre el tema se comentaba que construir una cultura fuerte de preparación previa era prácticamente imposible. Todos llegaban sin haber podido prepararse por la reunión inmediatamente anterior, y lo mismo pasaba con esa reunión anterior. En teoría se podría criticar preguntando por qué no reducir simplemente la cantidad de reuniones, pero en la práctica esas reuniones sí aportaban valor y, aun contando el tiempo de lectura, se tomaban decisiones suficientes. Al final hay que enfocarse en los resultados, y parece que en Amazon sienten que las ventajas de este método superan sus desventajas
  • Se pregunta por qué importa tanto cuándo se lee el documento. Si hace falta más tiempo, la reunión puede durar más. La desventaja sería que resulta más difícil agendarla, pero la opinión es que el tiempo total invertido no cambia
  • Cree que se pierde más tiempo cuando no todos tienen el mismo nivel de comprensión o cuando existe el temor de que se escape algún caso límite de alguien
  • Cuenta la experiencia de que, si algo no se trata en la reunión, simplemente no pasa nada
• Hay muchos consejos excelentes sobre claridad y edición. La debilidad está en cómo se gestionan los documentos después de ser aprobados. Sin mantenimiento, terminan degradándose a un estado de "arqueología del diseño". Hace unos años Andrew Harmel-Law propuso los Architecture Decision Records (ADRs) como una forma efectiva de registrar decisiones de arquitectura dentro de una organización, y eso podría ayudar. Los ADRs viven junto al código, por ejemplo adr/001-use-postgres.md, y registran de forma breve el contexto, la decisión y el estado. La ventaja es que pueden revisarse fácilmente en cada PR y reemplazarse con facilidad cuando cambian las circunstancias. Además, los motivos de la decisión original siguen siendo buscables incluso meses después. [Enlace: https://martinfowler.com/articles/…]
  • Se pregunta si con este enfoque los comités de toda la organización, como Security, Privacy o Compliance, terminarían siendo revisores en cada PR que incluya ADRs. Duda que esos PR puedan mergearse en menos de 90 días
  • Dice que tendría que leer completo el enlace de MF.com(https://thoughtworks.com/radar/techniques/…), pero el "Advice Process" termina con la frase "habla con todos". Cree que cualquiera con el cargo de "Managing" perdería el interés en ese punto. El verdadero núcleo, dice, son los "cuatro elementos de apoyo". Entró a este enlace para averiguar más sobre ADRs y acabó descargando un PDF(https://thoughtworks.com/content/dam/…). Le gustaría una definición más clara de qué son realmente los ADRs
  • Session messenger es un ejemplo representativo. Ha tenido tantos cambios de diseño y arquitectura que no existe una fuente autorizada que explique oficialmente cómo funciona. Por cierto, si se necesita mensajería segura, mejor usar Signal
• En su experiencia, la organización y la claridad son los mayores obstáculos para que los ingenieros de software mejoren su capacidad de redacción. Cree que la analogía del autor sobre el "código espagueti" es un buen ejemplo para explicar la importancia de organizar las ideas. Él mismo había intentado transmitir algo parecido de otra manera, y piensa usar esa analogía en adelante. Hace tiempo escribió un post similar(https://ryanmadden.net/things-i-learned-at-google-design-docs/) y le parecieron interesantes tanto las coincidencias como las diferencias entre empresas, como la densidad de información y la importancia de la práctica. Sobre la idea de los "párrafos cortos", discrepa un poco. Los párrafos salen cortos cuando la información está bien refinada; no sirve de mucho solo meter saltos de línea. Cree que la sección sobre "Editing" explica mejor esa idea de fondo
• Tiene un proceso que usa al escribir. Paso 1: vaciar en el documento todo lo que se le ocurra, sin orden alguno, incluso usando dictado si hace falta. Paso 2: intentar que un LLM (modelo de lenguaje grande) le dé estructura y flujo. De hecho, en esta etapa puede acabar desechando el resultado, porque sigue afinando las ideas. Paso 3: usar el resultado del LLM como referencia, o directamente hacer un esquema nuevo, para redactar el primer borrador. Paso 4: hacerlo lo más conciso posible, recortando palabras, cambiándolas por otras más simples, etc. Paso 5: repetir el paso 4. El LLM funciona como un puente para estructurar un borrador caótico. También hace falta estar dispuesto a tirar lo que produzca. Siempre se puede recortar al menos un 30%. Le sigue sorprendiendo ver cuánto puede reducirse un texto sin perder significado
  • Siente que editar de nuevo lo que escribe es tan importante como escribirlo por primera vez. Ahí descubre qué tan apresuradas fueron sus conclusiones y qué cosas no había considerado. Cree que mucha gente no valora lo suficiente la escritura como herramienta para concentrar el pensamiento. Con el código pasa algo parecido. Incluso al escribir algo sencillo y de plantilla, muchas veces se le ocurren ideas para mejorar el código principal mientras escribe tests. Pero un LLM no le va a señalar ese tipo de oportunidades cualitativas de mejora
  • Es un proceso de expandir, recortar, comprimir, volver a expandir y volver a comprimir. Si alguien hace una pregunta específica, se vuelve a expandir, y al final usa un LLM para hacer un resumen ligero y entretenido. En esencia, es una montaña rusa sin fin
• Piensa que debería escribir más. Dos estructuras de documentos que considera representativas son B.O.O. y Good Strategy/Bad Strategy. B.O.O. significa Background, Objective, Overview, y sirve para ordenar cómo se llegó hasta aquí y qué se quiere cambiar y de qué manera. Good Strategy/Bad Strategy es un libro estructurado en diagnóstico, guía/prerrequisitos/requisitos y acción, y en términos de organización documental se parece a B.O.O. B.O.O. funciona bien en Google o en organizaciones pequeñas, mientras que Good Strategy/Bad Strategy puede aplicarse a escalas mucho más variadas, aunque exige un autor con buena pluma
• Tomó una clase de escritura técnica y mejoró mucho su capacidad para resumir con claridad los puntos clave. Se concentró en el método de "tachar con bolígrafo rojo" —escribir, tachar y volver a escribir—, que pone énfasis en transmitir un concepto con la menor cantidad posible de palabras. Ese proceso tiene varias etapas y se vuelve más fácil con la práctica. Intenta compartir esa capacidad con sus compañeros de equipo, pero siempre recuerda que es una habilidad que necesita entrenarse con regularidad
• Le gustan mucho tanto los documentos escritos de esta manera como la cultura de escritura en sí. Pero también ha visto casos donde este enfoque produce el efecto contrario. Explicar las razones y la lógica para llegar a una conclusión funciona muy bien en documentos persuasivos. Sin embargo, no siempre hace falta ese tipo de persuasión. A veces es mejor escribir la conclusión de forma directa desde el principio, sobre todo para lectores que confían en el autor. En muchos casos, el lector quiere conocer primero el punto principal en vez de agotarse siguiendo toda la lógica. Una vez que sabe la conclusión, recién entonces le interesa seguir el razonamiento en detalle
  • También funciona perfectamente una estructura que ponga un resumen arriba y deje debajo la explicación detallada y los fundamentos
• A menudo escribe documentos de diseño que quizá solo termine leyendo él mismo. Aun así, siente que dejarlo por escrito ya es algo poderoso. Cree que sería de gran ayuda contar con documentos de ejemplo reales para poder comparar la estructura de los suyos con la estructura final de otras personas