por Angela Zhang
como ingeniero de software, paso mucho tiempo leyendo y escribiendo documentos de diseño. Después de haber pasado por 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 genial.,
El artículo se divide en 4 secciones:
- ¿por Qué escribir un documento de diseño
- ¿Qué incluir en un documento de diseño
- Cómo escribir
- 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 planea 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 hacerte más efectivo al obligarte a pensar en el diseño y recopilar comentarios de los demás. La gente a menudo piensa 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. Si bien esos pueden ser efectos secundarios beneficiosos, no son el objetivo en sí mismos.
como regla general, si está trabajando en un proyecto que podría tomar 1 mes de ingeniero o más, debe escribir un documento de diseño. Pero no te detengas ahí: muchos proyectos más pequeños también podrían beneficiarse de un mini doc de diseño.
Genial!, Si todavía estás leyendo, crees 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 sobre el contenido, el estilo y el proceso de un buen documento de diseño.
¿Qué incluir en un diseño de doc?
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 comenzar, la siguiente es una lista de secciones que al menos deberías considerar incluir en tu próximo documento de diseño:
título y personas
el título de tu documento de diseño, el autor(es) (debe ser el mismo que la lista de personas que planean trabajar en este proyecto), el revisor(es) del documento (hablaremos más sobre eso en la sección Proceso a continuación), y la fecha en que este documento se actualizó por última vez.
resumen
un resumen de alto nivel que todos los ingenieros de la empresa deben entender y utilizar para decidir si es útil para ellos leer el resto del documento., Debe ser 3 párrafos máximo.
Context
una descripción del problema en cuestión, por qué este proyecto es necesario, lo que la gente necesita saber para evaluar este proyecto y cómo encaja en la estrategia técnica, la estrategia de producto o los objetivos trimestrales del equipo.,
objetivos y no Objetivos
la sección objetivos debe:
- describir el impacto impulsado por el usuario de su proyecto-donde su usuario puede 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 hojearlo y saber aproximadamente cuándo se realizarán diferentes partes del proyecto. Te animo a dividir el proyecto en hitos principales orientados al Usuario si el proyecto dura más de 1 mes.
Use fechas de calendario para tener en cuenta retrasos no relacionados, vacaciones, reuniones, etc., Debería ser algo como esto:
Start Date: June 7, 2018Milestone 1 — New system MVP running in dark-mode: June 28, 2018Milestone 2 - Retire old system: July 4th, 2018End Date: Add feature X, Y, Z to new system: July 14th, 2018
=»836d5cf9e7″> subsección aquí si la ETA de algunos de estos cambios de hito, por lo que las partes interesadas pueden 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 interactúan los usuarios con este sistema y/o cómo fluyen los datos a través de él.,
Una historia de usuario es una gran 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 de Arquitectura Técnica. Una vez más, Trate de caminar a través de una historia de usuario para concretar esto. Siéntase libre de incluir muchas subsecciones y diagramas.
proporcione una imagen general primero, luego complete muchos detalles. Apunte a un mundo donde pueda escribir esto, luego tomar unas vacaciones en una isla desierta, y otro ingeniero en el equipo puede simplemente leerlo e implementar la solución como lo describió.,
Soluciones Alternativas
¿Qué otra cosa se consideran cuando viene con la solución anterior? ¿Cuáles son los pros y los contras de las alternativas? ¿Ha considerado comprar una solución de terceros, o usar una de código abierto, que resuelva este problema en lugar de construir la suya propia?
Testabilidad, monitoreo y alerta
me gusta incluir esta sección, porque la gente a menudo lo trata como una idea tardía o lo omite todo, 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 llamadas y operaciones de desarrollo? ¿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 problema abierto del que no esté seguro, decisiones polémicas sobre las que le gustaría que los lectores opinaran, sugerencias de trabajo futuro, etc. Un nombre irónico para esta sección es las «incógnitas conocidas».,
análisis detallado y línea de tiempo
Esta sección será leída principalmente por los ingenieros que trabajan en este proyecto, sus líderes tecnológicos y sus gerentes. Por lo tanto, esta sección se encuentra al final del documento.
esencialmente, este es el desglose de cómo y cuándo planea ejecutar cada parte del proyecto. Hay mucho que entra en el alcance con precisión, por lo que puedes leer este post para aprender más sobre el alcance.
tiendo a tratar esta sección del documento de diseño como un rastreador de tareas de proyecto en curso, por lo que lo actualizo cada vez que cambia mi estimación de alcance., Pero eso es más una preferencia personal.
cómo escribirlo
ahora que hemos hablado de lo que entra en un buen documento de diseño, hablemos sobre el estilo de escritura. Te prometo que esto es diferente a tu clase de inglés del Instituto.
escribe lo más simple posible
no intentes escribir como los artículos académicos que has leído. Están escritos para impresionar a los revisores de revistas. Tu documento está escrito para describir tu solución y obtener comentarios de tus compañeros de equipo., Puede lograr claridad utilizando:
- palabras simples
- frases cortas
- listas con viñetas y/o listas numeradas
- ejemplos concretos, como «User Alice connects her bank account, then Add «
agregar muchos gráficos y diagramas
Los gráficos a menudo pueden ser útiles para comparar varias opciones potenciales, y los diagramas generalmente son más fáciles de analizar que el texto. He tenido buena suerte con Google Drawing para crear diagramas.,
sugerencia Pro: 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 tarde 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 # de filas de BD, # de errores de usuario, latencia — y cómo se escalan con el uso. ¿Recuerdas tus notaciones?
intenta ser gracioso
una especificación no es un artículo Académico. Además, a la gente le gusta leer cosas divertidas, por lo que esta es una buena manera de mantener al lector involucrado., Sin embargo, no exageres hasta el punto de alejarte de la idea central.
si usted, como yo, tiene problemas para ser gracioso, Joel Spolsky (obviamente conocido por sus talentos Cómicos)) tiene este consejo:
una de las formas más fáciles de ser gracioso es ser específico cuando no se requiere en lugar de decir «intereses especiales», digamos «granjeros avacados zurdos».»
haga la prueba escéptica
antes de enviar su Documento de diseño a otros para que lo revisen, hágalo pasar fingiendo ser el revisor. ¿Qué preguntas y dudas podrías tener sobre este diseño?, A continuación, dirigirse a ellos de forma preventiva.
haga la prueba de vacaciones
Si se va de vacaciones largas Ahora sin acceso a internet, ¿puede alguien en su equipo leer el documento e implementarlo como 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 darle comentarios útiles.
Process
Ah sí, la temida P-word., Los documentos de diseño le 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 para él.
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 conduciendo muchas de las decisiones, pero todos deberían participar en la discusión y aceptar el diseño., Así que el» tú «a lo largo de este artículo es un» tú » muy plural que incluye a todas las personas en el proyecto.
en segundo lugar, el proceso de diseño no significa que estés mirando la pizarra teorizando ideas. Siéntase libre de 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 usted absolutamente debe sentirse libre de escribir un poco de código desechable hacky para validar una idea., Para asegurarse de que solo escribe código exploratorio, establezca la regla de que ninguno de este código prototipo se fusiona con master.
después de eso, a medida que comiences a tener alguna idea de cómo llevar a cabo tu proyecto, haz lo siguiente:
- pídele a un ingeniero experimentado o Líder Técnico de tu equipo que sea tu revisor. Idealmente, esto sería alguien que es muy respetado y / o familiarizado con los casos extremos del problema. Sobornar con boba si es necesario.
- ir 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énzalos de que esto 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 cualquier solución específica., A menudo, incluso si la implementación sigue siendo la misma, su revisor puede señalar los casos de esquina que necesita cubrir, indicar cualquier área potencial de confusión y anticipar las dificultades que podría encontrar más adelante.
luego, después de haber escrito un borrador de su Documento de diseño, haga que el mismo revisor lo lea nuevamente y lo selle agregando su nombre como revisor en la sección título y personas del documento de diseño. Esto crea incentivos adicionales y responsabilidad para el revisor.,
en ese sentido, considere agregar revisores especializados (como SREs e ingenieros de seguridad) para aspectos específicos del diseño.
una vez que usted y el / los revisores firmen, no dude en enviar el documento de diseño a su equipo para obtener 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étete a responder a todas las preguntas y comentarios que la gente deje dentro de esa semana. Dejar comentarios colgando = mal karma.,
Por último, si hay mucha controversia entre usted, su revisor y otros ingenieros que leen el documento, recomiendo encarecidamente consolidar todos los puntos de controversia en la sección de discusión de su Documento. Luego, organice una reunión con las diferentes partes para hablar de estos desacuerdos en persona.
Cuando 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 usted todavía es responsable de hacer la llamada final, incluso si todos no pueden llegar a un consenso.,
al hablar con Shrey Banga recientemente sobre esto, aprendí que Quip tiene un proceso similar, excepto que además de tener un ingeniero experimentado o Líder Técnico en su equipo como revisor, también sugieren que un ingeniero en 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 la implementación!, Para obtener puntos extra, trate este documento de diseño como un documento vivo mientras implementa el diseño. Actualice el documento cada vez que aprenda algo que le lleve a realizar cambios en la solución original o actualizar su alcance. Me lo agradecerás más tarde cuando no tengas que explicar las cosas una y otra vez a todas tus partes interesadas.
finalmente, vamos a conseguir 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 es exitoso si se realiza el ROI correcto del trabajo.,de la arquitectura técnica
X es la parte más arriesgada de la arquitectura propuestaX primero para eliminar el riesgo del proyectoX no es posible, o mucho más difícil de lo que originalmente pretendíaAl principio 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 has pasado 8 días. Me parece un resultado bastante exitoso.
Por favor, deje un comentario a continuación si tiene alguna pregunta o comentario! También me encantaría saber cómo diseñas documentos de manera diferente en tu equipo.
dando crédito donde se debe crédito, aprendí mucho de lo anterior trabajando junto a algunos ingenieros increíbles en Plaid (¡estamos contratando! Ven 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 backend.