Como ingeniero de software, dedico mucho tiempo a leer y escribir documentos de diseño. Después de haber revisado cientos de estos documentos, he visto de primera mano una fuerte correlación entre los buenos documentos de diseño y el éxito final del proyecto.
Este artículo es mi intento de describir lo que hace que un documento de diseño sea excelente .
El artículo se divide en 4 secciones:
- Por que escribir un documento de diseño
- Qué incluir en un documento de diseño
- Como escribirlo
- El proceso a su alrededor
¿Por qué escribir un documento de diseño?
Un documento de diseño, también conocido como especificación técnica, es una descripción de cómo planeas resolver un problema.
Ya hay muchos escritos sobre por qué es importante escribir un documento de diseño antes de sumergirse en la codificación. Así que todo lo que diré aquí es:
Un documento de diseño es la herramienta más útil para asegurarse de que se realiza el trabajo correcto.
El objetivo principal de un documento de diseño es hacerlo más efectivo al obligarlo a pensar en el diseño y recopilar comentarios de los demás. La gente suele pensar que el objetivo de un documento de diseño es enseñar a otros sobre algún sistema o servir como documentación más adelante. Mientras que los que puede haber efectos secundarios beneficiosos, que son no la meta en sí mismos.
Como regla general, si está trabajando en un proyecto que puede llevar 1 mes de ingeniero o más, debe escribir un documento de diseño. Pero no se detenga ahí: muchos proyectos más pequeños también podrían beneficiarse de un mini documento de diseño.
¡Excelente! Si todavía está leyendo, cree en la importancia de los documentos de diseño. Sin embargo, diferentes equipos de ingeniería, e incluso ingenieros dentro del mismo equipo, a menudo escriben documentos de diseño de manera muy diferente. Así que hablemos del contenido, el estilo y el proceso de un buen documento de diseño.
¿Qué incluir en un documento de diseño?
Un documento de diseño describe la solución a un problema. Dado que la naturaleza de cada problema es diferente, naturalmente querrá estructurar su documento de diseño de manera diferente.
Para empezar, la siguiente es una lista de secciones que al menos debería considerarincluyendo en su próximo documento de diseño:
Título y personas
El título de su documento de diseño, elautor (es) (debe coincidir con la lista de personas que planean trabajar en este proyecto), el (los) revisor (es)del documento (hablaremos más sobre eso en la sección Proceso a continuación) y la fecha de la última actualización de este documento.
Visión general
Un resumen de alto nivel que todo ingeniero de la empresa debería comprender y utilizar para decidir si es útil para ellos leer el resto del documento. Debe tener un máximo de 3 párrafos.
Contexto
Una descripción del problema en cuestión, por qué es necesario este proyecto, qué necesitan saber las personas para evaluar este proyecto y cómo encaja en la estrategia técnica, la estrategia del producto o las metas trimestrales del equipo.
Metas y no metas
La sección de Objetivos debe:
- describir el impacto de su proyecto impulsado por el usuario, donde su usuario podría ser otro equipo de ingeniería o incluso otro sistema técnico
- especificar cómo medir el éxito utilizando métricas: puntos de bonificación si puede vincular a un panel que rastrea esas métricas
Los no objetivos son igualmente importantes para describir qué problemas no solucionará para que todos estén en la misma página.
Hitos
Una lista de puntos de control medibles, para que su PM y el gerente de su gerente puedan leerla y saber aproximadamente cuándo se realizarán las diferentes partes del proyecto. Te animo a dividir el proyecto en hitos importantes para el usuario si el proyecto dura más de 1 mes.
Utilice las fechas del calendario para tener en cuenta retrasos no relacionados, vacaciones, reuniones, etc. Debería verse algo como esto:
Start Date: June 7, 2018
Milestone 1 — New system MVP running in dark-mode: June 28, 2018
Milestone 2 - Retire old system: July 4th, 2018
End Date: Add feature X, Y, Z to new system: July 14th, 2018
Agregue una [Update]subsección aquí si la ETA de algunos de estos hitos cambia, para que las partes interesadas puedan ver fácilmente las estimaciones más actualizadas.
Solución existente
Además de describir la implementación actual, también debe recorrer un flujo de ejemplo de alto nivel para ilustrar cómo los usuarios interactúan con este sistema y / o cómo fluyen los datos a través de él.
Un usuariohistoriaes una excelente manera de enmarcar esto. Tenga en cuenta que su sistema puede tener diferentes tipos de usuarios con diferentes casos de uso.
Solución propuesta
Algunas personas llaman a esto la sección Arquitectura técnica . Nuevamente, intente recorrer una historia de usuario para concretar esto. No dude en incluir muchas subsecciones y diagramas.
Primero proporcione una imagen general, luego complete los lotesdedetalles. Apunta a un mundo en el que puedas escribir esto, luego tómate unas vacaciones en una isla desierta, y otro ingeniero del equipo puede simplemente leerlo e implementar la solución como lo describiste.
Soluciones alternativas
¿Qué más consideró al llegar a la solución anterior? ¿Cuáles son los pros y los contras de las alternativas? ¿Ha considerado comprar una solución de terceros, o utilizar una de código abierto, que resuelva este problema en lugar de crear la suya propia?
Testabilidad, monitoreo y alerta
Me gusta incluir esta sección, porque las personas a menudo tratan esto como una ocurrencia tardía o se saltan todos juntos, y casi siempre vuelve a morderlos más tarde cuando las cosas se rompen y no tienen idea de cómo o por qué.
Impacto entre equipos
¿Cómo aumentará esto la carga de las operaciones de desarrollo y las llamadas?
¿Cuánto dinero costará?
¿Causa alguna regresión de latencia al sistema?
¿Expone alguna vulnerabilidad de seguridad?
¿Cuáles son algunas consecuencias negativas y efectos secundarios?
¿Cómo podría el equipo de soporte comunicar esto a los clientes?
Preguntas abiertas
Cualquier tema abierto sobre el que no esté seguro, decisiones polémicas sobre las que le gustaría que los lectores opinen, trabajos futuros sugeridos, etc. Un nombre irónico para esta sección es "incógnitas conocidas".
Alcance y cronograma detallados
Esta sección la leerán principalmente los ingenieros que trabajan en este proyecto, sus líderes técnicos y sus gerentes. Por lo tanto, esta sección se encuentra al final del documento.
Básicamente, este es el desglose de cómo y cuándo planea ejecutar cada parte del proyecto. Hay muchas cosas relacionadas con el alcance preciso, por lo que puede leer esta publicación para obtener más información sobre el alcance.
También tiendo a tratar esta sección del documento de diseño como un rastreador de tareas del proyecto en curso, por lo que actualizo esto cada vez que cambia mi estimación de alcance. Pero eso es más una preferencia personal.
Como escribirlo
Ahora que hemos hablado sobre lo que implica un buen documento de diseño, hablemos del estilo de escritura. Prometo que esto es diferente a la clase de inglés de la escuela secundaria.
Escribe de la forma más sencilla posible
No intente escribir como los artículos académicos que ha leído. Están escritos para impresionar a los revisores de revistas. Su documento está escrito para describir su solución y obtener comentarios de sus compañeros de equipo. Puede lograr claridad usando:
- Palabras simples
- Oraciones cortas
- Listas con viñetas y / o listas numeradas
- Ejemplos concretos, como "La usuaria Alice conecta su cuenta bancaria y luego ..."
Agregue muchos gráficos y diagramas
Los gráficos a menudo pueden ser útiles para comparar varias opciones potenciales y, por lo general, los diagramas son más fáciles de analizar que el texto. He tenido buena suerte con Google Drawing para crear diagramas.
Consejo profesional: recuerde agregar un enlace a la versión editable del diagrama debajo de la captura de pantalla, para que pueda actualizarlo fácilmente más adelante cuando las cosas cambien inevitablemente.
Incluir números
La escala del problema a menudo determina la solución. Para ayudar a los revisores a tener una idea del estado del mundo, incluya números reales como el número de filas de la base de datos, el número de errores de usuario, la latencia y cómo estos escalan con el uso. ¿Recuerdas tus notaciones Big-O?
Trata de ser gracioso
Una especificación no es un trabajo académico. Además, a la gente le gusta leer cosas divertidas, así que esta es una buena forma de mantener al lector interesado. Sin embargo, no exagere con esto hasta el punto de alejarse de la idea central.
Si usted, como yo, tiene problemas para ser gracioso, Joel Spolsky ( obviamente conocido por su talento para la comedia ...) tiene este consejo:
Una de las formas más fáciles de ser gracioso es ser específico cuando no es necesario [… Ejemplo:] En lugar de decir "intereses especiales", di "agricultores de aguacates zurdos".Haz la prueba escéptica
Antes de enviar su documento de diseño a otras personas para que lo revisen, hágase pasar por el revisor. ¿Qué preguntas y dudas tienes sobre este diseño? Luego, abórdelos de manera preventiva.
Haz la prueba de vacaciones
Si se va de vacaciones largas ahora sin acceso a Internet, ¿alguien de su equipo puede leer el documento e implementarlo como lo pretendía?
El objetivo principal de un documento de diseño no es compartir conocimientos, pero esta es una buena manera de evaluar la claridad para que otros puedan realmente brindarle comentarios útiles.
Proceso
Ah, sí, la temida palabra P . Los documentos de diseño lo ayudan a obtener comentarios antes de perder mucho tiempo implementando la solución incorrecta o la solución al problema incorrecto. Hay mucho arte para obtener buenos comentarios, pero eso es para un artículo posterior. Por ahora, hablemos específicamente sobre cómo escribir el documento de diseño y obtener comentarios al respecto.
En primer lugar, todos los que trabajan en el proyecto deben ser parte del proceso de diseño. Está bien si el líder tecnológico termina impulsando muchas de las decisiones, pero todos deben participar en la discusión y aceptar el diseño. Entonces, el “tú” a lo largo de este artículo es un “tú” realmente plural que incluye a todas las personas en el proyecto.
En segundo lugar, el proceso de diseño no significa que esté mirando la pizarra teorizando ideas. No dude en ensuciarse las manos y crear prototipos de posibles soluciones. Esto no es lo mismo que comenzar a escribir código de producción para el proyecto antes de escribir un documento de diseño. No hagas eso. Pero definitivamente debería sentirse libre de escribir algún código descartable para validar una idea. Para asegurarse de que solo escribe código exploratorio, establezca como regla que ninguno de este código prototipo se fusiona con el maestro .
Después de eso, cuando empiece a tener una idea de cómo llevar a cabo su proyecto, haga lo siguiente:
- Pídale a un ingeniero experimentado o líder técnico de su equipo que sea su revisor. Idealmente, sería alguien muy respetado y / o familiarizado con los casos extremos del problema. Sobornarlos con boba si es necesario.
- Vaya a una sala de conferencias con una pizarra.
- Describa el problema que está abordando a este ingeniero (este es un paso muy importante, ¡no lo omita!).
- Luego, explique la implementación que tiene en mente y convéncelos de que es lo correcto para construir.
Hacer todo esto incluso antes de comenzar a escribir su documento de diseño le permite obtener comentarios lo antes posible, antes de invertir más tiempo y apegarse a una solución específica. A menudo, incluso si la implementación sigue siendo la misma, su revisor puede señalar los casos extremos que debe cubrir, indicar las áreas potenciales de confusión y anticipar las dificultades que podría encontrar más adelante.
Luego, después de que hayas escrito un borrador de tu documento de diseño, haz que el mismo revisor lo lea de nuevo, y séllelo agregando su nombre como revisor en la sección Título y Personas del documento de diseño. Esto crea un incentivo y una responsabilidad adicionales para el revisor.
En ese sentido, considere agregar revisores especializados (como SRE e ingenieros de seguridad) para aspectos específicos del diseño.
Una vez que usted y los revisores firmen, no dude en enviar el documento de diseño a su equipo para recibir comentarios adicionales y compartir conocimientos. Sugiero limitar el tiempo de este proceso de recopilación de comentarios a aproximadamente 1 semana para evitar retrasos prolongados. Comprométase a abordar todas las preguntas y comentarios que la gente deje dentro de esa semana. Dejar comentarios colgando = mal karma.
Por último, si hay mucha discordia entre usted, su revisor y otros ingenieros que leen el documento, le recomiendo encarecidamente que consolide todos los puntos de discordia en la sección Discusión de su documento. Luego, programe una reunión con las diferentes partes para hablar sobre estos desacuerdos en persona.
Siempre que un hilo de discusión tiene más de 5 comentarios, pasar a una discusión en persona tiende a ser mucho más eficiente. Tenga en cuenta que todavía es responsable de tomar la decisión final, incluso si no todos pueden llegar a un consenso.
Al hablar con Shrey Banga recientemente sobre esto, me enteré de que Quip tiene un proceso similar, excepto que además de tener un ingeniero experimentado o un líder técnico en su equipo como revisor, también sugieren que un ingeniero de un equipo diferente revise el documento. No he probado esto, pero ciertamente puedo ver que esto ayuda a obtener comentarios de personas con diferentes perspectivas y mejorar la legibilidad general del documento.
Una vez que haya hecho todo lo anterior, ¡es hora de comenzar con la implementación! Para obtener puntos extra, trate este documento de diseño como un documento vivo a medida que implementa el diseño . Actualice el documento cada vez que aprenda algo que lo lleve a realizar cambios en la solución original o actualizar su alcance. Me lo agradecerá más tarde cuando no tenga que explicar las cosas una y otra vez a todos los interesados.
Por último, vamos a ponernos realmente meta por un segundo: ¿Cómo evaluamos el éxito de un documento de diseño?
Mi compañero de trabajo Kent Rakip tiene una buena respuesta a esto: un documento de diseño tiene éxito si se realiza el ROI correcto del trabajo. Eso significa que un documento de diseño exitoso podría conducir a un resultado como este:
- Pasas 5 días escribiendo el documento de diseño, esto te obliga a pensar en diferentes partes de la arquitectura técnica.
- Recibe comentarios de los revisores que
Xes la parte más riesgosa de la arquitectura propuesta - Decide implementar
Xprimero para eliminar el riesgo del proyecto - 3 días después, se da cuenta de que
Xno es posible o es mucho más difícil de lo que pretendía originalmente. - Decide dejar de trabajar en este proyecto y priorizar otro trabajo en su lugar
Al comienzo de este artículo, dijimos que el objetivo de un documento de diseño es asegurarse de que se realice el trabajo correcto. En el ejemplo anterior, gracias a este documento de diseño, en lugar de perder potencialmente meses solo para abortar este proyecto más tarde, solo ha pasado 8 días. Me parece un resultado bastante exitoso.
¡Deje un comentario a continuación si tiene alguna pregunta o comentario! También me encantaría saber cómo se diseñan documentos de manera diferente en su equipo.
Dando crédito a quien se debe el crédito, aprendí mucho de lo anterior trabajando junto a algunos ingenieros increíbles en Plaid (¡estamos contratando! Venga a diseñar y construir algunos sistemas técnicos dulces con nosotros) y Quora.
Si te gusta esta publicación, sígueme en Twitter para obtener más publicaciones sobre ingeniería, procesos y sistemas de backend.