¿Cuál es una forma efectiva de registrar las razones detrás de las decisiones de diseño de productos?

En nuestra empresa, no utilizamos ningún documento de diseño de productos. Tenemos un total de tres empleados, por lo que toda la discusión sobre el diseño del producto se realiza en persona o en Slack. (También estamos en el paquete básico de Slack que solo permite ver los mensajes más recientes).

Nuestro producto aún se encuentra en las primeras etapas, y a menudo revisamos los elementos de diseño que se decidieron hace meses.

Un problema que enfrentamos de manera angustiosa y frecuente es olvidar por qué se tomó una decisión de diseño del producto. Esto resulta en horas desperdiciadas recauchutando el mismo terreno.

¿Cómo podemos registrar efectivamente los fundamentos detrás de las decisiones de diseño?

Nuestro flujo de trabajo se basa en Pivotal Tracker. Una solución que se me ocurre es registrar los fundamentos de todas las decisiones de diseño relevantes como comentarios sobre la propia historia del usuario, pero esto parece poco confiable.

Para ser 100% claro: no estoy hablando del diseño de código. Estoy hablando del diseño del producto que se realiza mediante el código. En otras palabras, no estoy hablando de decisiones como "¿deberíamos estructurar esta clase usando composición en lugar de herencia múltiple?"; Me refiero a decisiones como "¿deberíamos solicitar a un usuario que confirme su dirección de correo electrónico antes de poder iniciar sesión?".

El propósito de la documentación es permitir que la empresa vea un registro de por qué se tomaron decisiones, para ayudar a tomar decisiones adicionales sobre los mismos temas.

Usted registra los fundamentos de las decisiones de diseño al escribirlas. Idealmente cerca del elemento que está sujeto a la decisión (que no es una "historia de usuario"; las historias de usuario son descripciones de lo que debe implementarse, no cómo).

Para eso están especialmente los comentarios : para registrar por qué una pieza específica de código o estructura se ve así (y no estoy hablando exclusivamente de comentarios de código). Si el tema de su diseño es una función, haga un comentario introductorio a la función. Si se trata de una clase, haga un comentario al comienzo de una clase sobre la justificación. Si tiene un montón de clases que deben seguir la misma estructura, agregue un documento de diseño separado (como un archivo "readme") al paquete que contiene esas clases. Si el tema de su diseño es un diagrama UML, agregue comentarios a la sección de descripción del diagrama.

Los documentos de diseño de la OMI pueden tener su valor, pero si describen cosas demasiado "alejadas" del elemento que describen, tienden a volverse inconsistentes muy rápidamente. Por lo tanto, mi recomendación es colocar la documentación de diseño lo más cerca posible del elemento diseñado.

Utilice documentos separados solo cuando desee documentar decisiones de diseño que afectan a muchos lugares diferentes de su código de manera transversal. Cuando los use, intente hacerlos parte de su base de código y colóquelos en el nivel de jerarquía correspondiente del tema diseñado (por lo tanto, si toma una decisión de diseño para un módulo que consta de muchos archivos de código fuente, coloque la descripción del diseño " dentro de "ese módulo, pero no en un archivo de clase, no en una" descripción de nivel superior "que sea válida para otros módulos, y definitivamente no en un Wiki separado fuera de su SCCS. Si desea registrar algún producto de" alto nivel " decisiones de diseño amplias, luego un documento de nivel superior puede ser el mejor lugar, pero asegúrese de que este documento se mantenga en ese nivel de abstracción.

Considere un enfoque ágil. Quiero decir, si tiene los recursos de tiempo y excelentes habilidades de escritura para escribir cada decisión de diseño que tomen junto con sus fundamentos, simplemente documenten todo. Hablando de manera realista, supongo que no estás en esa posición. Un enfoque ágil puede ayudar con un desafío clave para la documentación de los fundamentos: a menudo no se sabe cuáles eran los fundamentos importantes hasta más tarde.

Abordemos el problema desde un punto de vista holístico. Ustedes tienen razones para su decisión. Están atrapados en squishyware en este momento, los cerebros del equipo. A pesar de la cantidad de documentación crediticia que se obtiene, el almacenamiento de las razones en sqishyware no es tan malo. En realidad, somos muy buenos como especie para recordar las cosas importantes. Es por eso que todas las grandes corporaciones tienen "conocimiento tribal", incluso cuando esas corporaciones buscan documentar todo ese conocimiento tribal.

Ahora tienes un problema. Está descubriendo que el sqiushyware no se aferra a los fundamentos lo suficientemente bueno. ¡Bien por darte cuenta de que hay un problema e identificar que debe resolverse! ¡Eso no siempre es un paso fácil! Así que estamos bastante seguros de que la solución es descargar parte de esa lógica en la documentación. Sin embargo, eso no es suficiente. Nunca podemos olvidar la segunda mitad del rompecabezas, que es volver a cargar la lógica en el Squishyware cuando necesitas tomar una decisión. He visto muchos equipos que documentan todo como locos, pero el contenido no está realmente organizado para ayudar a tomar buenas decisiones, por lo que terminan olvidando los fundamentos aunque estén escritos .

Entonces tienes un proceso de dos pasos. Debe obtener la justificación del squishyware y llevarlo a la documentación. ¡Entonces debe asegurarse de que la documentación esté organizada lo suficientemente bien como para devolver lo racional a Squishyware cuando lo necesite! Ahora creo que tenemos suficiente enunciado del problema para darnos cuenta de dónde les gustarán los desafíos. Cuando está documentando, por lo general no sabe quién lo va a ver más tarde o qué está buscando. Del mismo modo, cuando mira hacia atrás a la documentación, generalmente no sabe lo que está buscando (en el mejor de los casos, puede saber cuándo).

Entonces, una gran empresa puede tratar de manejar esto en dos grandes bloques. Primero, pueden ir desarrollando requisitos basados ​​en lo que las personas necesitan cuando están investigando la documentación. Luego usan esos requisitos para construir un proceso para desarrollar dicha documentación. Y, si me atrevo a decirlo, entonces todos se quejan porque casi nadie sabe exactamente cómo debería ser la documentación el primer día. La documentación siempre está incompleta, y los desarrolladores siempre se quejan de que el proceso es demasiado pesado.

Hora de ir ágil.

Mi consejo sería comenzar un esfuerzo ágil para mejorar su proceso de documentación: los nueve metros completos desde squishyware a document y de vuelta a squishyware. ¡Reconozca por adelantado que perderá algo de información porque su proceso no es perfecto, pero está bien porque todavía está tratando de resolver el proceso! Te perderías más si intentaras crear una solución única para todos.

Algunas cositas particulares que miraría: * Explore la documentación informal. La documentación formal es excelente, pero lleva mucho tiempo. Uno de los propósitos de la documentación es liberar información del software blando desarrollador y ponerla en papel. La documentación informal mantiene el costo de hacerlo al mínimo.

• Acepte formatos de documentación poco confiables. Nada estará bien la primera vez. Es mejor obtener los datos y descubrir cómo hacerlos confiables más adelante. Por ejemplo, puede documentar sus fundamentos en un bloque <rationale> </rationale> o algo similar, lo que facilitaría la recolección de esos datos más adelante. Almacenar los fundamentos en una historia de usuario, por ahora, ¡está bien!
• Nunca olvides el valor de la organización. Descubra cómo a usted, como equipo, le gusta buscar fundamentos en la documentación e intente documentarlo. Cada equipo tendrá un proceso diferente. En uno de mis equipos, nunca pudimos encontrar el boleto que tenía la justificación inmediata. Lo que podríamos hacer es encontrar una línea de código que importara, hacer una svn blamepara saber cuándo cambió y por qué, luego ir a ver los boletos. Una vez que estuvimos allí, generalmente colocamos toda la justificación que necesitábamos en el boleto. Eso funcionó para nosotros, descubra lo que funciona para usted.
• La documentación orgánica puede crecer con el tiempo. Es raro que los desarrolladores sepan qué razones son más importantes el día que necesitaban escribirlo. Generalmente descubrimos cuáles fueron importantes más adelante. Si tiene un proceso de preparación para la documentación que permite a los desarrolladores administrar su propio pequeño jardín de fundamentos, los importantes saldrán a la superficie. Aún más importante, los fundamentos pueden cambiar. Puede darse cuenta de que dos cambios diferentes, con dos razones diferentes, se describieron realmente mejor con una única razón que funcione para ambos. ¡Ahora hay menos contenido entre usted y las decisiones!

Sugeriría configurar una instancia privada de MediaWiki o algún software wiki similar. Es realmente fácil organizar y reorganizar el contenido allí, y puede copiar y pegar nuevas discusiones directamente en la pestaña de discusión de los artículos wiki relevantes. Usamos MediaWiki en mi último trabajo para todos nuestros documentos de arquitectura y API, y fue un salvavidas.

Piénselo desde el punto de vista del codificador al que se le pedirá que lo cambie dentro de 12 meses.

Si agrega esta regla comercial como una prueba automatizada, se realizará el cambio Y ENTONCES obtendrá de la prueba reprobatoria el requisito contradictorio (y esperamos que capture a la persona asociada con el requisito original y su razón para especificarlo).

Considero que el documento de diseño (el lugar donde coloca sus diagramas BPMN, diagramas de transacciones, incluso una foto de la pizarra, etc.) es similar al código, solo una forma no ejecutable ... lo que significa lo que está intentando record es similar a un comentario de código, pero un requisito (comprobable) especificado por adelantado en el diseño. Presumiblemente, si usted es una tienda ágil, aún diseña su código, simplemente lo hace en el último minuto antes de escribirlo. Mantenga esto en la base del código con todos los demás documentos del proyecto.

Hagas lo que hagas, asegúrate de que esté almacenado de forma que se pueda buscar (por ejemplo, es posible que desees extraer todas las reglas comerciales relacionadas con la "autenticación" al especificar nuevos cambios).

Como siempre cuando escribes algo, debes preguntarte quién es el público objetivo. Creo firmemente que los documentos de diseño están ahí para mis desarrolladores pares, actuales o futuros. El documento les ayuda a comprender lo que estoy construyendo o lo que se construyó (descripción general de alto nivel) y, lo que es más importante, por qué. Es un lugar para documentar las alternativas que consideró, los pros y los contras de cada uno.

Decir que está bien que algún diseño viva en el cerebro de las personas deja de lado que los desarrolladores continúen y encuentren diferentes trabajos, llevándose consigo esa valiosa información.

Que su código sea la única documentación de diseño es como orientarse por la ciudad con una lupa. Un mapa es mucho más útil (desafortunadamente no hay un equivalente de GPS para el código fuente).

Estoy de acuerdo en que la documentación de diseño se pudre incluso más rápido que el código. Y dado que no hay validación posible entre los dos, lo único que puede hacer es mantenerlos juntos. OMI, un documento de diseño con fecha todavía proporciona información valiosa.