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!