Exprimiendo Scrum: Scrum y la documentación

Lo importante es no pasarse con la documentación ;)Recientemente he estado dando formación sobre Scrum a un grupo de profesionales del departamento de desarrollo de uno de los principales periódicos españoles. Se trataba más de gente que gestionaba desarrollo que de gente que desarrollase ellso mismo. Me ha encantado este curso por un motivo: la aproximación crítica que han tenido hacia lo que yo le he estado enseñando sobre Scrum. Alguno de los asistentes al curso dijo ‘yo estoy haciendo de abogado del diablo, aunque Scrum me gusta y nos puede servir, quiero buscarle las cosquillas’. Este enfoque, compartido por varios de los asistentes hizo que yo tuviese que exprimir al máximo las capacidades de Scrum y mis conocimientos sobre el tema para dar soluciones a las interesantes cuestiones que se plantearon.


También estoy actualmente ayudando a implantar Scrum y Team System a una importante editorial de temas jurídicos, y muchas de las cuestiones que voy a comentar en esta serie de artículos han sido planteadas por ellos. En este segundo caso se trata de un grupo de desarrolladores, más que de un grupo de gestores de proyectos y las cuestiones que plantean son en general de tipo más práctico, menos organizativo. No deja de sorprenderme que Scrum sea mucho más fácil de enseñar, diría yo más natural para desarrolladores que para gestores. Es increíble con que naturalidad estos han asumido Scrum como metodología.

Entre estos dos grupos de personas, se han planteado un motón de dudas que me van a permitir ‘exprimir Scrum’ en una serie de post.

Una de las personas del primer grupo que comentaba antes, conoce RUP. En RUP los artefactos juegan un papel esencial en el ciclo de vida del proyectos. RUP describe alrededor de uno 100 artefactos, aproximadamente la mitad de ellos son documentos. Queda claro que en RUP la documentación a generar es un aspecto central de la metodología. De hecho todo proyecto debe empezar por seleccionar cuales de los artefactos vamos a utilizar y adaptarlos a nuestras necesidades, pues evidentemente 50 documentos suponen una burocracia insostenible para la grandísima mayoría de proyectos de desarrollo de software. Aunque el volumen de documentos es mucho menor el enfoque en MSF es en cierto modo similar a el de RUP.

Una vez dicho esto, creo que ya todos podéis adivinar cual fue una de las primeras preguntas que esta persona hizo después de que yo contase en que consiste Scrum: con cierto tono de sorpresa y desconfianza preguntó, ¿no dice nada Scrum sobre que documentos se deben generar?. Mi respuesta fue: No. Y claro para alguien que ‘viene’ de RUP esto es inconcebible. Pero, logicamente, este no que yo di por respuesta tiene muchos matices. Scrum no impone ni sugiere ninguna documentación ni ningún circuito de documentación. No son documentos los que marcan el ciclo de vida, sino las actividades del equipo y la diferentes reuniones que mantienen.

Entendiendo como documentación la relativa a la arquitectura, desarrollo, mantenimiento, operación y despliegue del sistema desarrollado. Si que existen en Scrum algunos artefactos que suelen tener un soporte documental asociado: el Product Backlog, el Sprint Backlog, o un acta que recopile las cuestiones comentadas durante el Sprint Review, pero no tienen una forma estándar ‘impuesta’ por la metodología.

El planteamiento en Scrum, como metodología ágil que es, se basa en el principio del Manifiesto Ágil que dice: ‘Valorar más el software que funciona que la documentación exhaustiva’. Solo lo que hace el software y lo bien que lo hace es medida del progreso del proyecto.

El enfoque en en Scrum (y en el resto de metodologías ágiles) es asumir que el código es la única fuente de verdad sobre un proyecto de software a nivel de detalle, y el nivel de detalle es el único valido para modificar, extender o mantener un programa. Se entiende aquí como código, no solo el código ‘compilable’ sino, la documentación directamente asociada al mismo o embebida en él (comentarios que permitan generar documentación por ejemplo, con NDoc o JDoc) o aquella que se genera de manera automática desde el mismo (por ejemplo diagramas de clases que solo son otra vista del código). Baste recordar lo que todos hemos hecho para comprender un sistema del que disponíamos de su código fuente y que debíamos mantener o extender: leer el código, aunque exista documentación. Los desarrolladores preferimos leer código por que no es ambiguo y que siempre está actualizado. Lo que realmente tiene valor es contar con información directamente generada desde el código y sus comentarios en formato textual y descriptivo.

Otra documentación que no emana del código fuente directamente y que es de gran utilidad, si no imprescindible, es la relativa a arquitectura. Es necesario que un nuevo desarrollador o aquel que resucita el proyecto tras un tiempo pueda comprender que decisiones de alto nivel guiaron el desarrollo. Esta documentación si que es valiosa puesto que sirve para comprender por que se tomaron determinadas decisiones que no se cambian con facilidad a lo largo del proyecto y proporciona una primera aproximación que siempre es necesaria. La arquitectura de una aplicación no suele cambiar a menudo, lo que cambia es la implementación, el código. Documentar la arquitectura y que alguien la comprenda es algo que se hace perfectamente en lenguaje textual y utilizando algunos diagramas. Esta documentación es simple de mantener porque es mucho más estática que la de diseño detallado. Además algo especialmente valioso de la documentación de arquitectura es que establece el lenguaje común, la nomenclatura propia y el estilo que va a guiar del desarrollo. Scrum no te dice que debes hacer tales o cuales diagramas, pero nada cierra la puerta a tener un documento, que, a grandes rasgos, explique la arquitectura de tu proyecto.

La principal fuente de información sobre que hace una pieza de software esta el nombre de los componentes, de las clases y de las funciones. La principal documentación con la contamos es el estilo de nomenclatura, la coherencia a la hora de nombrar cosas y una arquitectura general coherente. La principal fuente de información del software debe emanar de una serie de patrones que se repiten a lo largo del proyecto, tanto a nivel arquitectónico como de diseño y estos patrones donde viven es en el código. Además es fácil mantener una base de conocimiento sobre nuestro proyecto, basada en artículos cortos y con ejemplos, tipo “knowledge base”, de manera que sean fácilmente buscables. Por eso los wikis se están popularizando tanto como repositorios de información sobre proyectos, no imponen una estructura, son ágiles de mantener, fácilmente actualizables, fácilmente buscables y soportan muchos tipos diferentes de contenido.

No es que Scrum propugne que no hay que documentar nada. La idea en Scrum es no tener que quitar y ajustar artefactos, sino crear aquellos que nos sean útiles en cada momento, para nuestras necesidades puntuales. La idea es evitar caer en el error de generar documentos (y con ellos el coste de escribirlos y mantenerlos) solo porque la metodología lo exige, si generamos un documento debe ser porque es imprescindible, claramente útil para una actividad determinada. No todos los proyectos y equipos de desarrollo necesitan el mismo tipo de documentación.

En Scrum (y en el resto de metodologías ágiles) se tiende a sustituir la documentación por la comunicación: Es mucho más útil y más ágil discutir en torno a una pizarra un diseño, que escribirlo en papel y que alguien revise el documento. Si alquien tiene una duda sobre como implementar un requisito nada mejor que hablar con el Producto Owner para aclarar el tema.

También se tiende a sustituir la documentación por la refactorización: Si una pieza de software es compleja, tenemos dos posibles estrategias a la hora de hacerla entendible. La primera es documentarla, la segunda es, a base de refactorización y de mejorar el diseño, simplificarla para hacerla más clara. Se puede ganar mucho en la legibilidad de nuestro software simplemente eligiendo buenos nombres, evitando la funciones enormes, utilizando la documentación XML, limpiando la variables no utilizadas… La ventaja de este enfoque es que mejora objetivamente el software, haciéndolo más mantenible, más claro y que no necesita un artefacto externo que puede fácilmente quedar desactualizado.

Otro problema que Scrum no resuelve del todo es como documentar la captura detallada de requisitos, algo que siempre es un quebradero de cabeza. Si que define claramente en que momento del proyecto se refina los requisitos: durante el Sprint Planning Meeting. En ocasiones, aunque en las menos, el Product Backlog puede ser insuficiente. Por ejemplo, nuestro software, puede tener que hacer complejas operaciones de negocio que tendremos que entender en detalle y refinar para poder implementarlas. Nada impide en estos casos usar el mecanismo que más nos convenga para gestionar la situación: historias, sesiones JAD, casos de uso, escenarios, etc… Resumiendo, en nuestra mano queda el seleccionar aquellos artefactos que en cada situación pueden sernos útiles. Por ejemplo yo creo, aunque Scrum no dice nada al respecto, un documento de visión del proyecto de una o dos páginas puede sernos de un valor inestimable a lo largo de proyecto, no tiene un coste de realización alto y no quedará obsoleto pronto, luego ¿por qué no hacerlo siempre?

Otra cuestión es que a la hora de hacer documentos Scrum no nos proporciona plantillas, gracias a proyectos como ReadySet esto es un problema menor. Además si yo creo que un documento de visión puede ayudar, siempre podemos tomarlo prestado de RUP, MSF o de ReadySet y ajustarlo a nuestras necesidades.

11 comentarios en “Exprimiendo Scrum: Scrum y la documentación”

  1. Son muy interesantes tus aportaciones sobre Scrum. ¿Podrías facilitar bibliografía para aprender Scrum en profundidad?. Si también pudieras añadir algún buen libro sobre Team System pues perfecto. Enhorabuena por el blog.

  2. Si bien me parece que en algunas situaciones el hecho de elaborar algo que pueda quedar obsoleto parece prohibido en las metodolgías ágiles(o al menos en un tercer plano), esto no debe implicar que no elaboremos documentación allí donde el problema tratado sea complejo o donde sospechemos que de dejar una vía abierta a la ambigüedad, se traducirá en repeticion de reuniones y aclaraciones (sobre todo cuando no se alcancen las espectativas).

    Yo he experimentado la implantación y utilización de distintas metodologías y creo que está sobradamente demostrado que lo importante es que la aplicación funcione y que sea “fácilmente” mantenible por personas que incluso no intervinieron en su desarrollo. Tanto el código como la documentación generada deben realizarse teniendo en cuenta esto. Al final una aplicación es el equilibrio entre la funcionalidad solicitada, los recursos empleados, los plazos establecidos y los niveles de calidad definidos para el mismo. Una documentación exhaustiva no va a hacer funcionar una aplicación mejor ni una aplicación completamente funcional va a permanecer invariable en el tiempo aislada de una labo de modiicación y mantenimiento (aunque es una forma de garantizar algún que otro puesto de trabajo)

    La mejor solución, en mi opinión, es la de utilizar un wiki que soporte el control de versiones sobre la documetación generada. Este es apuntado por tí pero quiero destacarlo. Un wiki te permite crear una estructura personallizada para cada proyecto (o basarte en alguna predefinida), es muy fácil de modificar y siempre se encuentra actualizado. Si ademas posee control de versiones, nos ayuda a saber cual ha sido la evolución del proyecto. Amén de todo lo mencionado como la documentación incrustada en el código extraible automáticamente, nombramiento de los componentes con criterio y sentido, etc.

    Desde mi experiencia la documentacion identificada como fundamental en todo proyecto software es aquella en donde estan los requisitos y flujos de trabajo de alto nivel, aquella en donde se define la arquitectura de la solución, aquella donde se define el modelo de datos e información, y aquella que si bien no es exhaustiva en su contenido si que muestra un mapa de la interfaz (o de lso ficheros de configuración o parametrización). En estos documentos se debe realizar un esfuerzo por mantenerlos actualizados.

    La forma en que el equipo realice su labor teniendo en cuenta lo indicado en estos documentos debe formar parte de cada iteracion o sprint, dejando que sea éste a través del proceso iterativo quien estableza el “como”.

  3. Sin embargo, yo creo que la herramienta que mejor “comunica” son, sin duda, los escenarios. Son concretos, concisos, contrastables “contra todo” y perfectamente entendibles por cualquiera sea técnico o no. Aunque su generación puede demorarse eternamente. Básicamente hay que estar alerta y disciplinadamente no permitir que los escenarios se salgan de los objetivos básicos del proyecto y de los límites que la racionalidad impone. El documento de visión puede quedar muy bien en la memoria, pero aporta poco a la gestión del proyecto. Los escenarios pueden usarse “contra” el proyecto en cualquier momento. Unos escenarios visados por el cliente son una excelente defensa contra aquellos que no saben lo que quieren o que, al final del proyecto, se vuelven especialmente detallistas sobre aspectos que nunca se consideraron… Y lo mejor, es tan natural que es lo primero que usamos, de forma normalmente informal, cuando tenemos que empezar a abordar un nuevo proyecto ¿cierto o no? Pues formalicémoslo y trabajemos con ello.

  4. Hola Telémaco:

    Aunque comparto tu gusto por los escenarios y lo que comentas sobre tener cuidado en no prolongar excesivamente la fase de análisis de estos.

    Pero no estoy de acuerdo con tu idea de ‘congelar’ los escenarios, de utilizarlos para ‘defendernos de los que no saben lo que quieren’. Es nuestro trabajo el guiar al cliente en la búsqueda de ‘lo que quieren’. Si el cliente supuiese lo que quiere no nos llamaría. Es más, en mi opinión, debemos asumir que lo que quiere el cliente cambia a lo largo del proyecto y debemos informale de que eso va a ocurrir y de que nosotros lo asumimos en la medida de lo razonable.

    Cerrando la puerta al cambio, construiremos el sistema que el cliente describio al principio, con poca información sobre su necesidades, nuestras capacidades, la necesidades de su negocio y lo que la tecnología empleada puede hacer. Pero nuestro trabajo es construir lo que el cliente necesita, y eso en mi opinión exije asumir el cambio como algo natural al proceso de desarrollo y explicarle al cliente lo que esto conlleva.

    En resumen, si usamos una metodología ágil como es Scrum, no podemos olvidar el manifiesto ágil: “Valorar más la respuesta al cambio que el seguimiento de un plan: Para un modelo de desarrollo que surge de entornos inestables, que tienen como factor inherente al cambio y la evolución rápida y continua, resulta mucho más valiosa la capacidad de respuesta que la de seguimiento y aseguramiento de planes pre-establecidos. Los principales valores de la gestión ágil son la anticipación y la adaptación; diferentes a los de la gestión de proyectos ortodoxa: planificación y control para evitar desviaciones sobre el plan.” (fuente: Wikipedia)

  5. Saludos muy buen articulo

    quisiera consultarte algo, si bien scrum no da pautas de documentacion en el sprint, a tu juicio q artefactos se podrian añadir al sprint para tener una documentacion minima???, y asi asegurar trazabilidad. agregandole lo anterior ya no seria scrum si no un scrum++

    saludos

  6. Manuel, cada equipo y cada proyecto necesitan un tipo y una cantidad de documentación diferente. Puedes usar UML, historias de usuario, escenarios, listas de riesgos, diagramas de clases de VS, etc… lo que necesites y segirás dentro de Scrum.

    La clave es hacer solo la documentación que necesites no hacer cierta documentación por sistema y sobre todo solo hacer documentación que aporte algún valor. Otra cosa que debemos perseguir es automatizar al máximo la generación de documentación.

  7. NDoc y SandCastle son las dos típicas herramientas de generación de documentación desde el código en plataforma .Net.

    En C/C++, la herramienta que yo usaba era Doxygen.

    ¡Un saludo!

  8. Me parece bastante parcializada la apreciación sobre el tema de la documentación, el ciclo de vida que debe de tener un producto de software y las apreciaciones sobre los roles de jefes de proyecto, analistas funcionales y programadores. En el artículo se habla de la “increíble naturalidad con que los programadores asumen Scrum como metodología” y el problema que supone para el resto el asimilar algunos conceptos propios de esta metodología (como el preguntar “si no existen documentos en SCRUM”). Definitivamente es parcializada y está escrito desde la perspectiva de un programador. NO ES POSIBLE CONDUCIR PROYECTOS DE SOFTWARE (ya sea pequeños o grandes) sin el soporte documental. Por un sin numero de motivos, relacionados a la formalización de los requerimientos con el cliente (o áreas cliente) y la necesidad de dejar “huella” del trabajo y funcionamiento de los mismos… Definitivamente el artículo tiene puntos importantes, pero quisiera advertir a los interesados en temas de Ingeniería de Software, a cerca del matiz netamente técnico de quien escribe.

  9. Hola JRLM,

    creo que hay algunas cosas que conviene aclarar con respecto a la documentación y Scrum como metodología ágil y que igual dan respuesta a tus dudas.

    La premisa más importante de todas es que Scrum no es incompatible con la documentación.

    Adicionalmente, Scrum no aboga por evitar, suprimir o eliminar la documentación. Esta es una afirmación que algunos formadores de Scrum citan de forma COMPLETAMENTE errónea incluso después de muchos años de formación y demuestra confusión al respecto (de ahí la entrada de Rodrigo ¡de hace casi 5 años! para aclarar estos aspectos).

    Por último, cabe destacar dos puntos.

    El primero de ellos es que Scrum no hace hincapié alguno en la documentación tal y como hacen otras metodologías, por lo que cada empresa, equipo, personas, etc., son libres de ajustar Scrum a sus necesidades.

    El segundo de ellos es que Scrum no indica que haya que finalizar ninguna documentación para iniciar el proyecto, si bien, aboga por centrarse en lo verdaderamente importante (el Software) por encima de la documentación.

    Todo lo anteriormente comentado, significa que tenemos cierta flexibilidad para hacer las cosas, si bien, NO es incompatible empezar a desarrollar Software sin tener toda la documentación completa.

    De hecho, es un cambio de chip que es importante hacer y que reconozco que cuesta, pero que cuando lo haces una primera vez, te das cuenta de que es posible.

    No obstante, cada empresa, equipo de trabajo, etc. es diferente, así que ni Scrum vale para todo el mundo, ni todas las empresas, personas, etc., para Scrum.

    Scrum debe ser un medio, no un fin.

    Un saludo.

    Jorge

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *