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.