- En Google, un Design Doc es un documento que, antes de programar, organiza el contexto del problema, la estrategia de implementación de alto nivel y las decisiones clave de diseño para reducir riesgos cuando el costo de diseño aún es bajo
- El valor del documento no está en explicar el código terminado, sino en hacer visibles los trade-offs y las alternativas para que la organización comparta la misma base de criterio
- Un buen Design Doc incluye, según el proyecto, el contexto y alcance, objetivos y no objetivos, el diseño real, las alternativas consideradas y preocupaciones transversales como seguridad, privacidad y observabilidad
- Si el diseño ya está claro o el documento solo enumera procedimientos de implementación, el overhead de redactar y revisar un Design Doc puede ser mayor que sus beneficios
- El documento pasa por redacción, revisión, actualización durante la implementación, mantenimiento y aprendizaje, y si el diseño cambia antes del lanzamiento, conviene actualizarlo también
El papel que cumple un Design Doc
- En Google, un Design Doc es un documento relativamente informal que el autor principal de un sistema o aplicación de software crea antes de comenzar un proyecto de programación
- Incluye la estrategia de implementación de alto nivel y las decisiones clave de diseño, pero más que una simple lista de decisiones, lo importante son los trade-offs que muestran por qué se eligió ese camino
- Como el objetivo de la ingeniería de software no es producir código por sí mismo sino resolver problemas, en las primeras etapas de un proyecto el texto no estructurado puede ser más conciso y fácil de entender que el código
- El Design Doc cumple varios roles dentro del ciclo de vida de desarrollo
- Detecta problemas de diseño temprano, cuando el costo de cambiar es bajo
- Forma consenso de diseño dentro de la organización
- Ayuda a no pasar por alto preocupaciones transversales como seguridad, privacidad y observabilidad
- Extiende el conocimiento de ingenieros senior al resto de la organización
- Conserva la memoria organizacional sobre decisiones de diseño
- Se convierte en un entregable que resume el portafolio técnico del diseñador
Estructura básica de un Design Doc
- Un Design Doc no tiene una plantilla estricta, y el primer principio es elegir el formato que mejor se adapte al proyecto específico
- Aun así, una estructura que suele ser útil puede organizarse en contexto y alcance, objetivos y no objetivos, diseño real, alternativas consideradas, preocupaciones transversales y una longitud adecuada
-
Contexto y alcance
- Ofrece una visión general aproximada del entorno donde se ubicará el nuevo sistema y de lo que realmente se va a construir
- No es un documento de requisitos, así que debe ser conciso y enfocarse en ayudar al lector a ponerse al día rápidamente con el contexto
- Puede asumir cierto conocimiento previo y enlazar detalles mediante links
- Esta sección debe centrarse en hechos de contexto objetivos
-
Objetivos y no objetivos
- Resume los objetivos del sistema y, a veces más importante, los no objetivos en una lista corta de viñetas
- Los no objetivos no son una simple negación del objetivo, como “el sistema no debe fallar”, sino elementos que podrían haber sido objetivos pero que se excluyeron explícitamente
- En diseño de bases de datos, el cumplimiento de ACID es un buen ejemplo de algo que conviene saber si es objetivo o no objetivo
- Incluso si algo es un no objetivo, se puede elegir una solución que ofrezca esa propiedad si no introduce trade-offs que dificulten alcanzar los objetivos
Cómo escribir el diseño real
- La sección del diseño real debe comenzar con una visión general y luego bajar a los detalles
- El Design Doc es el lugar donde se registran los trade-offs que surgieron en el diseño del software
- A partir de los hechos del contexto y de los requisitos definidos por objetivos y no objetivos, debe proponer una solución y mostrar por qué esa solución específica satisface mejor los objetivos
- Una ventaja del formato documental es que permite elegir con flexibilidad la forma de expresión que mejor se ajuste al conjunto de problemas
-
Diagrama de contexto del sistema
- En muchos documentos puede ser útil un system-context-diagram
- Este diagrama muestra el sistema como parte de un entorno técnico más amplio y ayuda al lector a entender el nuevo diseño dentro de un entorno que ya conoce
-
API y almacenamiento de datos
- Si el sistema que se diseña expone una API, por lo general conviene bosquejar la API
- Se debe evitar copiar y pegar definiciones formales de interfaces o datos tal cual
- Estas definiciones suelen volverse verbosas, incluir detalles innecesarios y quedar obsoletas rápidamente
- Conviene enfocarse en las partes relacionadas con el diseño y los trade-offs
- Un sistema que almacena datos debe tratar cómo se guardan y en qué forma aproximada
- Es mejor explicar las partes relacionadas con las decisiones de diseño que pegar la definición completa del esquema
-
Código y pseudocódigo
- En general conviene incluir muy poco código en un Design Doc
- Salvo cuando se explica un algoritmo nuevo, el pseudocódigo también debería usarse rara vez
- Si existe un prototipo que demuestre que el diseño es implementable, se puede enlazar cuando corresponda
El grado de restricciones cambia la forma del documento
- Uno de los principales factores que influyen en la forma del diseño de software y del Design Doc es el grado de restricciones en el espacio de soluciones
- En un extremo están los proyectos greenfield de software, donde solo existen los objetivos y prácticamente cualquier solución es posible
- Estos documentos pueden abarcar un rango amplio, pero necesitan definir rápido reglas para acotar el problema a un conjunto manejable de soluciones
- En el otro extremo están los sistemas donde las soluciones posibles están bien definidas, pero no está claro cómo combinarlas para alcanzar los objetivos
- Puede tratarse de un sistema legacy difícil de modificar
- Puede tratarse del diseño de una librería que debe funcionar dentro de las restricciones del lenguaje host
- En estos casos se pueden enumerar tareas relativamente sencillas, pero hace falta combinarlas de manera creativa para lograr los objetivos
- Si varias soluciones son imperfectas, el documento debe concentrarse en elegir la mejor con base en los trade-offs identificados
Alternativas y preocupaciones transversales
-
Alternativas consideradas
- Esta sección enumera los diseños alternativos con los que razonablemente se podría haber logrado un resultado similar
- Debe enfocarse en los trade-offs que genera cada diseño y en cómo esos trade-offs llevaron a la elección final
- Las soluciones no elegidas pueden tratarse de forma concisa, pero esta sección es muy importante dentro del documento
- Debe mostrar por qué otras soluciones que al lector podrían parecerle razonables resultan menos deseables a la luz de los objetivos del proyecto
-
Preocupaciones transversales
- A través de esta sección, una organización puede asegurarse de que siempre se consideren preocupaciones transversales como seguridad, privacidad y observabilidad
- Normalmente consiste en secciones breves que explican cómo cada preocupación afecta al diseño y cómo se resuelve
- Cada equipo debe decidir qué preocupaciones tomará como estándar según su situación
- Los proyectos de Google requieren un Design Doc de privacidad separado por su importancia, además de revisiones dedicadas de privacidad y seguridad
- La revisión completa es obligatoria para la fecha de lanzamiento del proyecto
- La práctica recomendada es colaborar con los equipos de privacidad y seguridad lo antes posible para que el diseño lo refleje desde el inicio
- Si existe documentación dedicada para ese tema, el Design Doc central puede referenciarla sin repetir los detalles
Longitud y casos en los que no hace falta escribirlo
-
Longitud adecuada
- Un Design Doc debe ser lo bastante detallado, pero también lo bastante corto como para que gente ocupada realmente lo lea
- En proyectos grandes, alrededor de 10 a 20 páginas parece ser un punto razonable
- Si se vuelve mucho más largo, puede ser mejor dividir el problema en subproblemas más manejables
- También es posible hacer mini Design Docs de 1 a 3 páginas
- Son especialmente útiles para mejoras incrementales o subtareas dentro de proyectos ágiles
- Siguen los mismos pasos que un documento largo, pero de forma más concisa y enfocada en un conjunto de problemas más limitado
-
Cuándo no hace falta escribir uno
- Redactar un Design Doc tiene overhead
- La decisión de escribirlo depende de si sus beneficios —como consenso de diseño, documentación y revisión por parte de seniors— superan el costo de producirlo
- El criterio clave es si el problema de diseño es ambiguo o no
- Puede ser ambiguo por la complejidad del problema, por la complejidad de la solución o por ambas
- Si no es ambiguo, el valor del proceso de documentación es pequeño
- Si el documento en la práctica es un manual de implementación, quizá no haga falta un Design Doc
- Si solo dice “lo voy a implementar así” y no explica trade-offs, alternativas ni decisiones, quizá habría sido mejor escribir directamente el programa
- Si la solución es tan obvia que no hay trade-offs, el valor del documento es bajo
- El overhead de redactar y revisar un Design Doc puede no encajar bien con el prototipado y la iteración rápida
- Seguir una metodología ágil no significa que se pueda dejar de pensar seriamente en la solución de problemas conocidos
- El prototipado mismo puede formar parte de la redacción del Design Doc, y “ya lo probé y funciona” puede ser una base muy sólida para una decisión de diseño
El ciclo de vida de un Design Doc
- El ciclo de vida de un Design Doc consta de cuatro etapas
- Redacción e iteración rápida
- Revisión
- Implementación e iteración
- Mantenimiento y aprendizaje
-
Redacción e iteración rápida
- El documento puede ser escrito por un solo autor o en conjunto con coautores
- Luego se comparte con colegas que conocen mejor el espacio del problema y se itera rápidamente
- Las preguntas de aclaración y sugerencias de los colegas llevan el documento hacia una primera versión relativamente estable
- En Google hay ingenieros y equipos que prefieren crear documentos con herramientas de control de versiones y revisión de código, pero la mayoría de los Design Docs se redactan en Google Docs y aprovechan mucho sus funciones de colaboración
-
Revisión
- En la etapa de revisión, el documento se comparte con un público más amplio que los colaboradores cercanos al autor original
- La revisión puede aportar mucho valor, pero también puede convertirse en una trampa de overhead, así que debe manejarse con cuidado
- Un enfoque liviano es enviar el documento a una mailing list más amplia del equipo para que la gente tenga oportunidad de revisarlo
- La discusión ocurre principalmente en los hilos de comentarios del documento
- Un enfoque más pesado es una reunión formal de revisión de diseño donde el autor presenta el documento ante ingenieros senior
- Muchos equipos de Google tienen reuniones periódicas para este tipo de revisión
- Esperar estas reuniones puede ralentizar considerablemente el proceso de desarrollo
- Esto puede mitigarse buscando directamente el feedback más importante y evitando que la revisión más amplia se convierta en un bloqueo para avanzar
- Cuando Google era una empresa más pequeña, era costumbre enviar los diseños a una sola mailing list central y que ingenieros senior los revisaran cuando tuvieran tiempo
- Ese enfoque tenía la ventaja de crear una cultura de diseño de software relativamente uniforme en toda la empresa
- A medida que la organización de ingeniería creció mucho, se volvió más difícil mantener ese enfoque centralizado
- El principal valor de la revisión está en crear la oportunidad de que la experiencia combinada de la organización se refleje en el diseño
- La etapa de revisión ayuda especialmente, de manera consistente, a que el diseño considere preocupaciones transversales como observabilidad, seguridad y privacidad
- El valor central de la revisión no es solo descubrir problemas, sino descubrirlos temprano en el ciclo de vida del desarrollo, cuando el costo de cambio todavía es bajo
-
Implementación e iteración
- Cuando ya existe confianza en que revisiones adicionales probablemente no exigirán grandes cambios al diseño, es momento de comenzar la implementación
- Cuando el plan choca con la realidad, pueden aparecer defectos, requisitos no contemplados o supuestos que resultan equivocados, y eso puede hacer necesario cambiar el diseño
- En ese caso, se recomienda fuertemente actualizar el Design Doc
- Como regla práctica, si el sistema diseñado aún no se ha lanzado, el documento debe actualizarse sí o sí
- En la práctica, muchas veces la gente no actualiza bien los documentos y por otras razones operativas los cambios terminan separados en nuevos documentos
- El resultado puede parecerse menos a un documento coherente y más a la Constitución de Estados Unidos con enmiendas anexas
- Si se dejan links desde el documento original hacia esos documentos de modificación, eso ayuda muchísimo a que un programador de mantenimiento entienda el sistema mediante una especie de arqueología de Design Docs
-
Mantenimiento y aprendizaje
- Cuando un ingeniero de Google se enfrenta por primera vez a un sistema, una de las primeras preguntas habituales es: “¿dónde está el Design Doc?”
- Como cualquier otra documentación, los Design Docs tienden a desalinearse de la realidad con el tiempo, pero a menudo siguen siendo el punto de entrada más accesible para entender el proceso de pensamiento con el que se construyó un sistema
- Conviene que el autor vuelva a leer su Design Doc después de 1 o 2 años
- Ver qué acertó
- Ver qué se equivocó
- Pensar qué decidiría distinto hoy
- El proceso de responder estas preguntas ayuda a crecer como ingeniero y a mejorar la capacidad de diseño de software con el tiempo
Cómo decidir si conviene empezar con un Design Doc
- Un Design Doc es una buena forma de obtener claridad y formar consenso al resolver problemas difíciles en un proyecto de software
- Puede ahorrar costos al reducir callejones sin salida de programación que se habrían evitado con investigación previa
- Al mismo tiempo, también tiene un costo porque redactarlo y revisarlo toma tiempo
- Se pueden considerar las siguientes preguntas
- ¿El diseño de software correcto es incierto, y vale la pena invertir tiempo por adelantado para ganar confianza?
- ¿Ayudaría involucrar en la etapa de diseño a ingenieros senior que quizá no puedan revisar todos los cambios de código?
- ¿El diseño de software es ambiguo o controversial, de modo que el consenso organizacional sería valioso?
- ¿El equipo a veces olvida reflejar en el diseño la privacidad, la seguridad, el logging u otras preocupaciones transversales?
- ¿Hace mucha falta dentro de la organización un documento que brinde una visión de alto nivel del diseño de sistemas legacy?
- Si respondes “sí” a 3 o más de estas preguntas, es muy probable que un Design Doc sea una buena forma de empezar tu próximo proyecto de software
1 comentarios
Opiniones de Hacker News
Dejé Google por su cultura de documentos de diseño
Poco después de entrar, escribí un documento que organizaba a un nivel muy alto una tarea relativamente menor que ya había hecho varias veces en otras áreas de producto, y un colega me llamó aparte para decirme: “aquí no hacemos las cosas así”
El enfoque que propuse era apenas una pequeña variación del método recomendado, pero me dijo que “evaluara más formas de hacer este trabajo”, y cuando pregunté por qué, respondió que “demuestra que lo consideraste de manera amplia”
En Google claramente existe el trabajo falso, y ojalá hubiera entrado a otro equipo
La cultura de Google terminó convirtiéndose en un culto cargo que se imita a sí mismo
Algunas empresas en las que trabajé después de Google eran reacias a hablar en detalle del proceso de ascenso, porque habían visto qué pasa cuando la gente microoptimiza para ajustarse a ese proceso
Como todos están ocupados, no se puede hablar informalmente 1:1 con cada persona, y si no consigues una revisión adecuada de los stakeholders, es probable que aparezcan personas molestas y te obliguen a revertir el lanzamiento
En este contexto, un documento de diseño es una herramienta de comunicación asincrónica para temas con mucha información. Si el producto tiene éxito, 10 años después seguirás conversando mediante ese documento con personas que se incorporaron entonces
Varias veces me salvó algún documento de diseño aleatorio de 2010 que explicaba decisiones extrañas que todavía nos frenan. Puede que no encaje bien con equipos pequeños y ágiles o tareas menos complejas, pero aunque en la cultura de ingeniería se haya convertido en culto cargo, en general tiene sus propios motivos y contexto
Si al diseñar algo solo tienes una solución en consideración, entonces no hay diseño o no fue lo suficientemente riguroso. Las opciones y los trade-offs son lo que hacen al diseño
Muchas de esas personas son consultores externos que llevan más de 15 años trabajando con la empresa, así que ya existe cierto estándar gracias a que las mismas personas han hecho las mismas tareas. Aun así, se empeñan en crear el hombre de paja de “qué pasa si la gente no sigue el estándar”
Como resultado, no hay documentos de diseño o están terriblemente obsoletos, y la empresa sigue contratando cada año a los mismos consultores con costos inflados
Ahora estoy en un equipo con muchos Googlers veteranos de más de 15 años de antigüedad, y los documentos de diseño existen solo cuando hacen falta. Por ejemplo, cuando abarcan varios sistemas o cuando claramente son complejos por la cantidad de trade-offs. Para todo lo demás, es simplemente “escribe los CLS”
En Google, los documentos de diseño parecen generar problemas porque son material clave que se incluye en los paquetes de promoción.
Por eso, los documentos terminan escribiéndose pensando más en el comité de promoción que en los lectores originales: las personas que trabajan en ese sistema.
Cada vez que entro a una empresa nueva, propongo que empecemos a escribir documentos de diseño, y eso de inmediato causa una buena impresión en la gerencia :)
Muchos de los documentos que leí parecían haber decidido ya la opción deseada y, al inicio del documento, haber agregado dos o más alternativas inventadas para hacer visible esa decisión. Contraponen una opción demasiado simple y otra con sobreingeniería innecesaria, y luego eligen la alternativa que parece razonable.
Como no saben qué documento de diseño usarán en su paquete de promoción, dejan documentado todo, por pequeño que sea, como documento de diseño. Existe el concepto de documento de diseño de una página, pero por lo general esa página crece hasta convertirse en varias.
Se escriben documentos de diseño incluso para proyectos de una semana, y me tocó revisar documentos de diseño de 20, 30 o 40 páginas para cosas que en otra empresa se habrían resuelto con un solo ticket de JIRA.
Mucha gente aprendió que el comité de promoción quiere ver “documentos escritos solo por el autor”, y, sea cierto o no, esa creencia hace que todo sea más lento y frena el aprendizaje cruzado. He visto ingenieros de software aislados durante más de un trimestre escribiendo solo documentos de diseño.
En un documento de diseño, el diseño real debería ser lo central, pero el 99% restante es definición del problema. Demasiadas veces, durante la revisión, al mejorar la definición del problema hubo que descartar el diseño y reescribir la mayor parte del documento.
Lo peor es cuando, al mejorar la definición del problema, aparece una solución simple que no requiere un diseño complejo. El autor ya invirtió mucho tiempo en el diseño complejo y, además, históricamente muchos comités consideraron esa complejidad como evidencia para una promoción, así que se resiste a la solución simple.
También vi documentos de diseño sin ninguna alternativa. Eran simplemente una descripción laboriosa de lo que había que hacer o de lo que alguien quería hacer.
Con el tiempo, si uno entrecierra los ojos, los documentos de diseño empiezan a parecerse a un sistema de seguimiento de bugs. Todos están trabajando en su propio documento de diseño y no en bugs, porque los bugs no te consiguen una promoción.
Cuando entras a un equipo nuevo, te dicen que basta con leer los documentos de diseño, pero en la práctica muchas veces no se rastrean de forma centralizada. En muchos equipos, los documentos de diseño no son propiedad del equipo ni del proyecto, sino de una persona, porque así se puede garantizar que nadie más contribuyó; y eso también es por el comité de promoción.
También hay muchos documentos de diseño a los que no tienes acceso, no porque sean ultrasecretos, sino simplemente porque así quedaron. No es que un equipo tenga dos o tres documentos de diseño: hay una montaña que leer. Con una rotación laboral en Google de alrededor de dos años, muchos documentos se pierden con el tiempo.
Es parecido a que en otra empresa le dijeran a alguien que acaba de entrar a un equipo nuevo: “todo lo que necesitas está en leer todos los bugs cerrados o todos los mensajes de commit de la rama principal”.
En otro lugar, después del almuerzo te habrían agarrado para pasar unas horas con el equipo frente a una pizarra definiendo el problema. Los seniors habrían enseñado en tiempo real a los juniors cómo pensar este tipo de problemas y habrían iterado rápido.
La mayor parte se habría escrito en el sistema de seguimiento de bugs o, si era algo grande, en la wiki o carpeta del proyecto, para que fuera propiedad de todos.
Todos los problemas anteriores pueden mejorar, y de hecho intenté mejorarlos, pero la cultura cambia lentamente. El concepto de documento de diseño en sí es bueno, pero tiene trampas, y la forma en que mucha gente en Google lo usa no es la respuesta.
Extraño los documentos de diseño cuyo valor era mayor que su costo.
En general, no vi que esa estrategia funcionara.
En cambio, sí había documentos largos para aportar contexto, que resumían qué había hecho el equipo, qué estaba haciendo y cuál era el problema, entre otras cosas; esos tendían a ser extensos y exagerados.
Trabajo en la empresa mencionada, pero mi experiencia no es la misma que la del autor.
Hay varios tipos de documentos de diseño, y ninguno de los que vi fue útil. Rara vez he visto un documento de diseño útil en Google. Los documentos de diseño se sienten como algo hecho para ingenieros demasiado orientados a los procedimientos.
Los tipos que he visto son más o menos estos: los documentos de diseño para ascender no explican qué intentan resolver; solo dicen lo maravilloso que es este proyecto y cómo hará mejor a la empresa. La conclusión lógica es que el autor debería recibir un ascenso.
Los documentos de diseño tipo turbo encabulator son textos de charla técnica llenos de términos que uno ve por primera vez, imposibles de entender a menos que seas senior del equipo. A veces ni siquiera estoy seguro de que los seniors los entiendan.
Los documentos de diseño de recién egresados no tienen contenido, pero están escritos de la forma más larga posible por alguien que acaba de salir de la universidad y quiere demostrar algo. No transmiten información y muchas veces llenan unas 70 páginas con grandes bloques de código ya escrito copiados y pegados.
Los documentos de diseño de hechos inventados están llenos de “todo el mundo sabe” y “todos dicen eso”. No son tan descarados como un político, pero empujan su diseño con frases como “esto sigue buenas prácticas” o “este software es lento, por lo tanto…”. Falta quién definió esas buenas prácticas, por qué son buenas, qué es lento, si se midió, o si es una percepción del usuario final.
El 99% de los documentos de diseño que vi eran así. Hay excepciones, pero por mi experiencia son muy raras. Me sorprende que el autor impulse esta práctica. Aunque, como era director y no ingeniero, quizá en ese puesto los documentos de diseño tengan sentido; igual sigo sin saber qué valor aportan esas personas.
[1] https://en.wikipedia.org/wiki/Turbo_encabulator
Algo que noté al principio fue que los documentos de diseño mantenidos en Google Docs tendían a ser de menor calidad que los que estaban en repositorios con control de versiones. No sé si eso era un indicador indirecto de cuándo se habían escrito, o si el proceso de revisión de código era más estricto que la edición en Docs.
Cuando escribí un documento de diseño grande, quizá de unas 40 páginas, lo hice, como era costumbre, en HTML escrito a mano y lo pasé por el sistema de revisión de código. También lo publiqué en una lista de correo central y en un servidor web, y fue bueno recibir feedback del empleado número 3. Estaba en una ubicación central, ordenado por categorías, así que era fácil de encontrar.
No recuerdo que un solo documento de diseño pesara lo suficiente como para ser importante para un ascenso. Los ascensos debían tratar sobre el impacto total, no sobre un entregable específico. Claro que el sistema tenía grandes defectos y a menudo producía decisiones sorprendentemente malas, pero en esa época no recuerdo haber leído documentos de diseño optimizados para evaluaciones de desempeño.
Si puedes encontrar el sitio web con la colección de los primeros documentos de diseño escritos a mano en HTML, recomiendo echarle un vistazo. Tal vez se habrían sentido más útiles cuando esos sistemas todavía estaban en producción.
Algunos de los documentos antiguos, como SmartASS, estaban llenos de explicaciones detalladas sobre las ecuaciones y modelos de base, y ayudaban mucho a entender cómo funcionaba y por qué se eligió ese enfoque. Más tarde influyeron también en mi propio trabajo de diseño. Yo no era director, solo un ingeniero, y de verdad me ayudaron.
Entre los documentos de diseño de Chrome enlazados desde el sitio chromium.org también hay algunos que en el pasado me ayudaron a entender la arquitectura.
Hacen que los desarrolladores junior piensen la solución de antemano y justifiquen sus decisiones, y permiten que los desarrolladores senior validen esas decisiones y den feedback asíncrono.
Dicho eso, siempre he trabajado en startups, así que nunca estuve en una organización de ingeniería de más de 30 o 40 personas. Big Tech será distinto, pero mi experiencia fue positiva.
Del mismo modo, si explicárselo a otro ingeniero toma mucho tiempo —aunque sean unos 30 minutos—, deberías escribir un documento para ahorrar tiempo.
No entiendo cómo alguien puede pensar que no necesita escribir documentación en absoluto.
Más adelante, cuando te preparas para un ascenso, terminas agregando suficiente contexto a los documentos de la categoría 2 para convertirlos en la categoría 1.
La documentación en general es buena, pero este enfoque parece tener fallas.
Dice que “antes de iniciar un proyecto de código”, el autor principal de un sistema o aplicación de software crea un documento relativamente informal, pero el diseño en sí es el proyecto de código, y ambas cosas son parte del mismo trabajo.
La idea de que puedes resolver todo el diseño en papel antes de hacer commits de código es incorrecta. El enfoque de documentos de diseño en realidad reconoce que hay que escribir algo de código al inicio, pero intenta encasillarlo estrictamente como “un prototipo que muestra la viabilidad de implementar el diseño”.
Una gran característica de los documentos de diseño previos es que dan permiso a la gente para poner objeciones, es decir, revisar, antes de que empiece la programación en serio. En mi experiencia, eso hace que el documento crezca cada vez más con salvedades y discusiones inútiles sobre alternativas, y termine siendo más un documento de “por favor, déjenme construir esto de una vez” que un documento de diseño.
Si hay problemas arquitectónicos importantes que requieren cambiar de dirección, es mejor hablar y colaborar antes con las personas adecuadas que crear un documento de diseño detallado y luego verlo derribado.
Si se mantiene más cerca de la idea de “documento relativamente informal” y se actualiza a medida que se avanza, puede ser realmente útil, porque permite crear al mismo tiempo un sistema funcional y documentación útil. Pero eso se parece menos a un documento de diseño y más a documentar como parte de un proceso continuo y colaborativo.
Soy Googler. También he publicado varios papers, pero antes odiaba escribir documentos de diseño. Desde hace unos años me di cuenta de los principales beneficios que me aporta
Me permite sacar de la cabeza la parte inmediata de las ideas y pasar a partes más profundas y a consideraciones productivas
Los defectos se ven mejor, sobre todo para mí mismo
Se vuelve más fácil compartir ideas, especialmente con gente de otras oficinas. Por lo general dan muy buen feedback
Me permite entender mucho mejor la cantidad de trabajo necesaria que cuando simplemente empiezo a programar
Normalmente revela cosas que hay que aprender antes de programar, sistemas adyacentes o la elección adecuada de tecnologías, etc.
También ayuda para los ascensos, pero un proyecto exitoso ayuda más. Como a menudo me dicen que mis documentos son útiles, parece que encontré un camino correcto
¿Realmente funciona? ¿Es mejor que las alternativas? ¿Dónde está esa discusión?
Cuando trabajé en Amazon, la cultura de documentos de diseño era excelente. Mi siguiente trabajo parecía haber tomado prestada la cultura de ingeniería de Google o la cultura típica de startups de SF, y el proceso de documentos de diseño parecía un chiste inútil
Son una pieza que encaja con una cultura laboral más amplia. Si trabajas solo, es un ejercicio lujoso; si estás en un equipo enorme, permite aprovechar más la experiencia de todo el equipo y también sirve como documentación
Hay varias formas de fracaso. Valorar el entregable por encima del resultado es una desalineación típica. Escribir un documento de 40 páginas para lograr un ascenso, por ejemplo, no suele funcionar salvo en casos muy junior en los que se demuestra que uno puede hilvanar frases más que hacer ingeniería profunda
También puede ser excesivo para equipos donde se trabaja en solitario. Otros equipos pequeños pueden comunicarse lo suficiente con issues, por ejemplo Jira, y sesiones separadas para contrastar ideas
Los ingenieros también deben recibir onboarding sobre cómo escribir documentos de diseño efectivos. El comentario superior, frustrado porque su primer intento no recibió elogios de inmediato, puede ser una señal
Escribir sobre código es difícil, y normalmente en HN se elogia este tipo de práctica. Si trabajas en equipo, conviene tener cuidado cuando sientes que tu trabajo siempre consiste solo en cosas que pueden explicarse en documentos compartibles y que no requieren pensar en profundidad
Si un gran inversionista ocultara su identidad y trabajara unas semanas como ingeniero de Google, de inmediato se convertiría en un inversionista activista que exigiría la destitución de Sundar
La escala del potencial humano desperdiciado por la cultura de documentos de diseño de Google es casi incomprensible
La mayoría del desarrollo simplemente avanza, y de vez en cuando se escribe un documento a las apuradas para que sea más fácil justificar un CL
En más o menos 1 de cada 10 casos veo a alguien exagerando demasiado, pero para el ingeniero de software promedio no es una gran pérdida de tiempo
Si quisiera quemar la mayor cantidad de dinero posible, creo que diseñaría la empresa exactamente así
La cultura de documentos de diseño tiende a empujar a todos hacia una capa de justificación de su propio trabajo. La cultura de justificación, aunque los colegas la refuercen culturalmente, es un patrón bastante opresivo para los innovadores
Este sistema tiende a bloquear intentos visionarios y proyectos ambiciosos. Los esfuerzos que no se basan en el consenso son sofocados, y si piensas “fuera de las normas permitidas”, el grupo te castiga
Estos sistemas generan pensamiento de grupo, y su carácter centrado en la tradición de “la forma en que trabajamos” básicamente impone una situación en la que trabajar de otra manera se vuelve riesgoso para la carrera
En Silicon Valley hay culturas corporativas de todo tipo que se apoyan en lugares comunes envueltos en términos como “ágil” y “design thinking”, y por lo general se parecen más a una institucionalización que finge ser “la forma correcta”, acompañada de elementos adicionales que imponen socialmente la variante de cultura de culto de ingeniería a la que llegó ese campus
He conocido a incontables personas, y no son pocas, que se fueron de Google diciendo que, aunque trabajar allí era muy cómodo, les limitaba la carrera
Expresaste exactamente la frustración que viví allí. Aun así, sí me gustaría volver a cobrar esa compensación
Sobre agile, yo lo conocí hace unos 20 años en la forma de eXtreme Programming, y no tenía nada que ver con el culto cargo de SCRUM o sus imitaciones de hoy
Al final era un conjunto de principios que le daban poder creativo al desarrollador, impedían que los managers se metieran en el cómo y permitían hacer el trabajo. A cambio, le daba al cliente autoridad para decir qué hacer, cuándo y en qué medida
Los desarrolladores estiman directamente, y el principio es “no construir lo que no se necesita”. No hay gran diseño por adelantado; refactoring y testing, arquitectura y diseño no son historias o tareas separadas, sino que forman parte del overhead continuo como buenas prácticas estándar
Las reuniones de planificación son colegas alineándose en una sala, y las historias se expresan en post-its en un pizarrón con un mínimo de términos no técnicos. Los standups son literalmente personas de pie en círculo dando actualizaciones muy breves, solo lo suficiente como para que a otros les pueda interesar, no un ritual para demostrar que hoy fuiste a trabajar ni para lucirte
En este sistema, el diseño es una propiedad emergente de un grupo creativo de especialistas trabajando juntos. No excluye documentos de diseño y todavía incluye discusiones de arquitectura, pero no exige un proceso explícito de PRD/documento de diseño
Me gustaría volver a trabajar en un lugar así. Google era exactamente lo contrario y todo tardaba demasiado
Este comportamiento falso de “somos muy inteligentes” también es una forma de trabajo inútil. La empresa debería enfocarse en productos que realmente funcionen y evaluarse a sí misma por eso
Otro Googler por aquí
Ya hay muchos buenos comentarios sobre que los documentos de diseño de Google no sirven, pero quiero sumar otra perspectiva sobre por qué lo siento como un problema
Como ya se mencionó, los documentos de diseño son material para ascensos, así que generan una enorme cantidad de relleno. Pero además parecen sustituir a la documentación real
Todos los documentos de diseño quedan prácticamente obsoletos en cuanto se terminan, pero los equipos apuntan a esos documentos en lugar de escribir documentación nueva. Como resultado, la documentación de Google es bastante mala y está desactualizada
Sinceramente, sería mucho mejor que, en vez de escribir 20 páginas sobre “trabajo no realizado”, contara para ascensos escribir una guía de uso de 2 páginas sobre cómo usar lo que realmente existe
¿Se pueden ver documentos reales? Los documentos del proceso de diseño de software parecen ser secretos guardados con el mayor celo. Nunca he visto documentos reales que se puedan usar para un estudio de caso
Kubernetes: https://github.com/kubernetes/enhancements/tree/master/keps
Ejemplo: https://rfd.shared.oxide.computer/rfd/0177
Índice principal: https://rfd.shared.oxide.computer