Un documento de diseño de software es un artefacto previo a la implementación que permite anticipar decisiones técnicas costosas, coordinarse con otros equipos y obtener retroalimentación antes de escribir código. Michael Lynch, ingeniero con experiencia en Google, Microsoft y sus propias empresas, comparte una guía práctica basada en años escribiendo estos documentos.
El artículo responde a tres preguntas clave. Primero, cuándo escribirlo: si el proyecto implica coordinación entre varias personas, supera los tres meses de trabajo, estará en producción durante años, requiere colaboración interequipos, tiene objetivos ambiguos o comporta riesgos catastróficos (seguridad, legales), conviene redactarlo; con dos o más respuestas afirmativas, es casi seguro que merece la pena. Segundo, cuánta profundidad dedicar: puede ir desde una página hasta cincuenta, y a veces la inversión correcta es cero. Tercero, qué incluir: solo las decisiones cuyo coste de equivocarse sea alto. Detallar decisiones triviales —como si mostrar 20 o 1.000 artículos por página— malgasta ciclos de revisión.
Entre los componentes recomendados figuran un título corto, distintivo y evocativo; metadatos básicos (autor, fecha, URL); un objetivo de una frase en lenguaje plano; un apartado de antecedentes con datos concretos (por ejemplo, el paso de 100 ms a 600 ms en tiempos de carga); y enlaces a documentos relacionados. Lynch ilustra cada sección con un ejemplo ficticio de capa de caché entre el servidor web Trogdor y una base de datos Postgres. La guía continúa con el proceso de revisión y la incorporación de feedback.