- Los design docs son uno de los elementos centrales de la cultura de ingeniería de software de Google, y son documentos relativamente informales que el autor principal de un sistema o aplicación de software redacta antes de comenzar un proyecto de programación.
- Documentan la estrategia de implementación de alto nivel y las principales decisiones de diseño, con especial énfasis en los trade-offs considerados al tomar esas decisiones.
- El trabajo de un ingeniero de software no es escribir código, sino resolver problemas, y el texto no estructurado como un design doc puede ser una herramienta de resolución de problemas más concisa y fácil de entender que el código en las primeras etapas de un proyecto.
El papel de los design docs en el ciclo de vida del desarrollo de software
- Además de la documentación original del diseño de software, cumplen funciones como las siguientes:
- Identificar problemas de diseño tempranamente, cuando los cambios todavía son baratos.
- Lograr consenso sobre el diseño dentro de la organización.
- Garantizar que se consideren las cross-cutting concerns.
- Difundir el conocimiento de los ingenieros senior dentro de la organización.
- Formar la base de la memoria organizacional sobre las decisiones de diseño.
- Servir como artefacto de resumen dentro del portafolio técnico de un diseñador de software.
Estructura de un design doc
- Como un design doc es un documento informal sin lineamientos estrictos de contenido, la regla es escribirlo en el formato que mejor se adapte a cada proyecto.
- Context and scope: ofrece una visión general del contexto en el que se construye el nuevo sistema y de lo que realmente se va a construir.
- Goals and non-goals: enumera los objetivos del sistema y lo que no forma parte de ellos.
- The actual design
- System-context-diagram: diagrama que muestra el sistema como parte de un entorno técnico más amplio.
- APIs: bosquejo de las APIs que expone el sistema.
- Data storage: discusión sobre cómo se almacenan y administran los datos.
- Code and pseudo-code: se incluye solo cuando se describen nuevos algoritmos.
- Degree of constraint: el nivel de restricciones del espacio de soluciones es uno de los factores principales que influyen en la forma del documento de diseño.
- Alternatives considered: enumera diseños alternativos que podrían lograr razonablemente resultados similares, y explica los trade-offs de cada uno y por qué se eligió el diseño principal.
- Cross-cutting concerns: explica cómo las preocupaciones comunes de la organización, como seguridad, privacidad y observabilidad, afectan el diseño.
Cuándo escribir un design doc
- La decisión de escribir o no un design doc depende de si sus beneficios —como el consenso organizacional sobre el diseño, la documentación y la revisión por parte de ingenieros senior— superan el trabajo adicional que implica redactarlo.
- Si no hay ambigüedad en la solución al problema de diseño debido a la complejidad del problema o de la solución, el valor de documentarlo es menor.
- Un design doc demasiado cercano a un manual de implementación puede ser innecesario.
- En el prototipado y la iteración rápida, la sobrecarga de escribir un design doc puede no ser adecuada.
Ciclo de vida de un design doc
- Creation and rapid iteration: redacción del documento y rápida iteración con colegas para llegar a una versión estable.
- Review: se comparte con una audiencia más amplia para su revisión.
- Implementation and iteration: si surgen cambios de diseño durante la implementación, el documento se actualiza.
- Maintenance and learning: sirve como el punto de entrada más accesible para entender el sistema.
Opinión de GN⁺
- Un design doc es una buena forma de obtener claridad y lograr consenso al resolver los problemas más difíciles de proyectos de software complejos. Puede reducir costos al evitar programación innecesaria mediante investigación previa, aunque al mismo tiempo también genera costos porque requiere tiempo para redactarlo y revisarlo.
- Por eso, conviene decidir con criterio si vale la pena escribir un design doc según el proyecto. Puede ser recomendable cuando hay incertidumbre en el diseño del software, cuando la intervención temprana de ingenieros senior ayuda, cuando se necesita consenso organizacional sobre el diseño, cuando el equipo suele pasar por alto preocupaciones comunes como la seguridad, y cuando hace falta documentación de alto nivel sobre el diseño de sistemas legacy.
- Es un caso que muestra bien la importancia de la documentación en el proceso de diseño de software, y parece especialmente útil para establecer una cultura de diseño consistente en equipos grandes. Aun así, como la carga de documentar puede hacer que los ingenieros lo eviten, parece importante definir lineamientos con un nivel y alcance adecuados para cada situación.
- Personalmente, creo que la utilidad de un design doc es grande en 1) considerar los trade-offs según la complejidad del diseño, 2) detectar problemas de diseño de forma temprana antes de implementar, y 3) ofrecer una visión general del sistema para que los nuevos integrantes aprendan rápido. Eso sí, hay que evitar que se convierta en un documento demasiado formal o desconectado de la implementación real.
- Una opción podría ser volver obligatorio el design doc solo al inicio del proyecto o en etapas de diseño con alta complejidad, y al mismo tiempo ofrecer incentivos para que los ingenieros lo redacten de manera voluntaria. También sería bueno destacar que escribir documentación puede fortalecer el portafolio técnico de cada ingeniero.
1 comentarios
Opinión de Hacker News
Diversas opiniones sobre la cultura de documentos de diseño en Google: