La tendencia a largo plazo hacia
la gestión ágil de proyectos
concede gran importancia a la eliminación de gastos generales innecesarios. Los proyectos avanzan más rápido que nunca, y es fácil etiquetar la documentación como un flujo de trabajo que produce poco valor en comparación con la producción de más código de calidad.
En este contexto
software
A menudo se apunta a la documentación como una actividad que debe reducirse. De hecho, “el software operativo por encima de la documentación exhaustiva” es
una regla clave para la gestión ágil
y la documentación aportan un valor real a largo plazo.
Principales ventajas de una documentación de software de calidad
- Las expectativas se mantienen controladas. Unos requisitos del proyecto cuidadosamente documentados ayudan a mantener un proyecto organizado, dentro del presupuesto y a tiempo.
- Se atienden las necesidades. La documentación técnica refleja los requisitos, peticiones, necesidades y particularidades del cliente, lo que permite a las partes gestionar los argumentos.
- Centrarse en el futuro da poder. Una documentación de calidad ayuda a garantizar que el futuro trabajo de desarrollo pueda ponerse en marcha, asegurando que su producto de software sea un activo flexible a largo plazo.
- Los equipos funcionan con cohesión. Una buena documentación facilita un traspaso óptimo del equipo de desarrollo a quienes gestionan activamente la aplicación (ya sea de cara al consumidor, B2B o interna).
Una planificación minuciosa garantiza el éxito.
Una documentación selectiva y adaptada a cada propósito preserva la
flexibilidad del desarrollo ágil
al tiempo que garantiza que los cambios se ciñan a un plan que satisfaga los requisitos básicos.
No hay duda de que Agile se está alejando de un enfoque rígido en la documentación exhaustiva de cada característica y decisión de codificación. Para reflejar el dinamismo del desarrollo ágil, las prácticas modernas de documentación deben ser adaptables sobre la marcha. La necesidad última de una documentación de calidad sigue existiendo.
En este artículo, desglosamos la documentación de los proyectos de software y ofrecemos algunas ideas para adoptar un enfoque basado en el valor. Empezaremos por identificar a continuación algunas categorías de alto nivel de la documentación de software.
Aspectos clave de la documentación de proyectos
- Requisitos
- Arquitectura/Diseño
- Técnico
- Usuario final
Documentación sobre desarrollo de software: Requisitos
Unos requisitos bien documentados ayudan a garantizar una cooperación eficaz y una comunicación clara cuando los desarrolladores trabajan para traducir los requisitos empresariales en especificaciones técnicas.
Los requisitos deben definir claramente lo que hay que hacer, junto con una comprensión precisa de cómo debe ser la tarea completada. Un documento de requisitos de software debe reflejar tanto los requisitos funcionales como las necesidades no funcionales (como el rendimiento y las capacidades de conmutación por error).
En un entorno ágil, los requisitos suelen originarse como historias de usuario. Pero el enfoque técnico preciso para apoyar estas historias de usuario en el producto de software final puede cambiar a lo largo del proyecto.
Un planteamiento flexible permite introducir cambios de forma rápida y sencilla durante el proceso de desarrollo del producto. La documentación de los requisitos nunca debe tratar de restringir esta flexibilidad, sólo asegurarse de que se hace un buen seguimiento de estos cambios tan rápidos.
Los jefes de proyecto desempeñan un papel fundamental a la hora de garantizar que todas las partes interesadas entiendan cómo afectará al proyecto en su conjunto el cambio de requisitos. Un enfoque flexible está muy bien, pero no se puede permitir que la aplicación se desvíe de la consecución de sus objetivos centrales (mientras que
respetar los plazos y el presupuesto
).
Para los equipos de desarrollo subcontratados, la relación entre los cambios en los requisitos y el
alcance del proyecto
dependerá del contrato empleado. Si el desarrollo se basa en un alcance fijo, los cambios en los requisitos tendrán que reflejarse en el
declaración de trabajo
(SOW).
A medida que estos cambios tienen lugar y se integran en el proyecto, la documentación del software puede reflejar exactamente qué función cumplen.
En el caso de un contrato por tiempo y materiales, el director de proyecto puede centrarse en el impacto práctico de los cambios de requisitos, diciendo por ejemplo: “Podemos añadir esta función, pero requerirá tres semanas más, un desarrollador más o dejar de lado otra función para esta iteración del producto”.
Documentación sobre desarrollo de software: Arquitectura/Diseño
Documentos de arquitectura de software se utilizan para realizar un seguimiento de las decisiones de más alto nivel tomadas sobre la estructura y el comportamiento del sistema. Esta documentación no sólo debe hacer un seguimiento de los requisitos, sino también de cómo se aplican las soluciones.
Ejemplos de documentación arquitectónica y de diseño
los siguientes:
Diagramas alámbricos
Estos diagramas destacan la funcionalidad y la interfaz de usuario (IU) de su software. Gracias a esta documentación, podrá hacerse una idea más clara del tipo de experiencia de usuario (UX) que pretende ofrecer con su software.
Los wireframes son muy codiciados por su amalgama de sencillez y detalle. Incluso cuando pierda a alguno de los principales desarrolladores o equipos de su software, los wireframes pueden ayudar a sus sucesores a tener una idea firme de la estructura y los objetivos principales de su software.
Bocetos de interfaz de usuario
Tanto si su software es B2B como B2C, una interfaz de apuntar y hacer clic es el alma de su funcionalidad. Un boceto de interfaz de usuario es la maqueta de la interfaz gráfica de usuario (GUI) que desea crear para sus usuarios finales.
Mediante los bocetos de interfaz de usuario en la documentación de software, los equipos de desarrollo pueden esbozar el enfoque inicial y final de la interfaz gráfica de su software. Esto permite a los desarrolladores que se incorporan saber con qué tipo de interfaz gráfica de usuario van a trabajar, lo que ayuda a establecer expectativas a través de señales visuales.
Descripciones topológicas
Las descripciones de topología le permiten asignar la funcionalidad y conectividad de su software a otras aplicaciones. Esto también le permite destacar la accesibilidad de su software a través de múltiples dispositivos y redes, lo que permite a su equipo de desarrollo supervisar los requisitos de conectividad de su aplicación.
Las descripciones topológicas son útiles en cualquier planteamiento de desarrollo de software. Pero son especialmente esenciales en el software empresarial, donde se desea perfilar la conectividad de la aplicación con otras redes de la organización. Por eso es un aspecto importante que hay que tener en cuenta al redactar la documentación.
Información sobre DevOps
El desarrollo ágil familiariza a su software con equipos de ingeniería interfuncionales y solapados. En cambio, DevOps se centra en implantar la colaboración entre los equipos de desarrollo y operativos. La combinación de ambos agiliza el desarrollo y la entrega de software, manteniéndose en línea con los objetivos de la organización.
Documentación sobre desarrollo de software: Técnica
La documentación técnica captura el código del programa. Dicha documentación incluye
lo siguiente
:
- Descripciones de API:
información útil para que los desarrolladores utilicen su API, conectando sus aplicaciones a su software.
- Listas de variables de entorno
:
variables de entorno que vinculan su software a determinados procesos.
- Archivos ReadMe
:
documentación de software que ayuda a sus desarrolladores y usuarios finales a conocer mejor las funcionalidades y operaciones de su aplicación.
No es de extrañar que a los programadores no les guste escribir documentación y prefieran limitarse a crear “código autodocumentado”. De hecho, diversas herramientas de automatización (por ejemplo, Swagger o Javadoc) permiten generar documentación actualizada en cualquier momento. Para los compañeros programadores, un código claro y bien estructurado puede necesitar pocas explicaciones.
Pero aunque la calidad del código es la base de una estrategia de documentación eficaz, ni siquiera el código más prístino será transparente para los no profesionales del desarrollo. La documentación garantiza que las unidades de negocio relacionadas dispongan de los recursos necesarios para ayudar a que el producto de software alcance todo su valor.
También cabe destacar que las pruebas unitarias desempeñan un papel importante en el proceso de documentación técnica. Para ahorrar tiempo, muchos desarrolladores prefieren evitar su uso ante la proximidad de los plazos. Sin embargo, las pruebas unitarias se utilizarán como especificaciones de código, lo que facilitará mucho el soporte a largo plazo para futuros cambios.
La incorporación es un buen ejemplo del tipo de necesidad operativa práctica a la que contribuye una documentación técnica de calidad. Una documentación de calidad garantiza que los nuevos miembros del equipo necesiten menos ayuda para aprender el funcionamiento del sistema y minimiza las posibilidades de que un equipo de desarrollo ocupado se olvide de mencionar un detalle crucial.
Onboarding también puede ofrecer una gran comprobación práctica de la calidad de su actual
documentación del software
. Si un nuevo miembro del equipo revisa la documentación existente y no parece estar al tanto de aspectos cruciales del proyecto, es posible que haya lagunas importantes que resolver.
Documentación sobre desarrollo de software: Usuario final
La documentación para el usuario final adopta la forma de diversos conjuntos de instrucciones, manuales de usuario y tutoriales para ayudar a los nuevos usuarios a emplear con éxito un producto de software.
Las aplicaciones modernas, web y móviles
no suelen
necesitan mucha documentación para el usuario final. Y un diseño de interfaz de usuario hábil e intuitivo minimiza sin duda la necesidad de manuales formales. Pero la aceptación por parte de los usuarios debe considerarse cuidadosamente como parte del proceso general de desarrollo: incluso unas pocas instrucciones sencillas pueden llegar muy lejos. Cuanto más útil sea un producto informático para sus usuarios, más valor generará. En un entorno B2B o de cara al consumidor, unas instrucciones cuidadosamente elaboradas pueden reducir drásticamente la necesidad de asistencia/formación en directo.
La documentación para el usuario final no tiene por qué ser una lectura tediosa. Mediante la creación de contenidos útiles y atractivos que se despliegan con su software, puede asegurarse de que sus usuarios finales tienen toda la información que necesitan para resolver por sí mismos los obstáculos más comunes. Esto contribuye a mejorar la experiencia de los usuarios, al tiempo que le ayuda a centrarse en el perfeccionamiento constante de su software en lugar de resolver por sí solo quejas evitables.
Siguiendo los planteamientos modernos, puede alojar esta documentación en su propio sitio web. Este alojamiento en la nube de la documentación evita que los usuarios finales tengan que cargar con varios archivos cuando utilizan su software, al tiempo que le permite integrar rápidamente cualquier actualización en su software.
documentación del software
a medida que se producen.
Desarrollo de software: Planificación relacionada
Este artículo se centra en la documentación del proceso de desarrollo y del producto de software. En particular, la documentación de desarrollo es sólo un aspecto de la planificación necesaria para maximizar el valor de un producto de software.
Preverlo todo, desde el marketing hasta el apoyo posterior al lanzamiento y la estrategia de producto, es esencial para el éxito final de un producto de software.
El valor de una documentación adecuada
La documentación de proyectos no es una ciencia exacta, y las prácticas deben ser lo suficientemente flexibles como para adaptarse al proyecto en cuestión: una documentación adecuada evitará tanto el trabajo de documentación superfluo como el tipo de trabajo mal documentado que resulta costoso.
En general, cuanto mayor y más complejo sea un producto de software, más documentación necesitará. Incluso en un mundo ágil, una aplicación empresarial grande con muchas integraciones complejas y funcionalidades secundarias puede requerir una documentación sustancial. Del mismo modo, una aplicación web sencilla puede necesitar una documentación muy reducida.
Cuando se trata de gestionar la documentación durante el propio proyecto, el tamaño del equipo es otra variable crucial.
Para un equipo más pequeño que se comunica con frecuencia sobre un proyecto, los check-ins a través de una plataforma como Slack pueden ser el único proceso necesario para mantener a los miembros del equipo informados de los cambios relevantes en la documentación. En cuanto a las herramientas, una empresa más pequeña que cree una aplicación relativamente sencilla puede limitarse a realizar un seguimiento de los proyectos en un documento de Word o SharePoint.
Para un equipo más grande, o un equipo que trabaja para una empresa más grande con procesos de informes internos más extensos, un enfoque más formalizado de la
documentación de software
y la comunicación en equipo.
Documentación cuidadosa pero práctica en la destilería
En Distillery, por ejemplo, utilizamos la gestión de proyectos basada en Jira y tenemos experiencia con herramientas como
Confluence
(una herramienta de documentación basada en wiki con plena integración en Jira). Aunque estas herramientas pueden hacer que crear y compartir documentación sea lo más fácil y transparente posible, no son en absoluto necesarias para crear documentación de calidad: también realizamos con éxito proyectos para clientes que emplean un enfoque mucho más sencillo de la documentación.
Sean cuales sean las herramientas empleadas, es responsabilidad del director del proyecto hacer un seguimiento de la forma en que cada miembro del equipo documenta su parte del proyecto, asegurándose de que se registran los conocimientos adecuados.
En Distillery, nuestro objetivo es siempre producir la cantidad de documentación necesaria para facilitar los objetivos del proyecto, ni más ni menos. Empleamos listas de comprobación, por ejemplo, para garantizar que se elabora la documentación adecuada en todos los ámbitos del proyecto.
Para un área determinada, como DevOps o arquitectura, la cantidad de documentación requerida por el proyecto en cuestión puede ser, de hecho, muy limitada. En general, el objetivo no es crear una documentación demostrativamente “exhaustiva”, sino evitar la toma de decisiones arbitrarias: tanto la documentación excesiva como la inadecuada tienen costes reales.
Hemos visto de cerca las dos caras de este riesgo de costes. En algunos casos, hemos participado en proyectos en los que los extensos requisitos de documentación requerían varias semanas de tiempo dedicado por parte de un desarrollador. También nos han llamado para trabajar en aplicaciones que otros proveedores dejaron insuficientemente documentadas; puede llevar mucho tiempo comprender la estructura del software y su entorno, aunque el código sea de calidad.
Cuando Distillery entrega un proyecto terminado a un cliente tras un ciclo de desarrollo satisfactorio, normalmente realizamos una llamada de entrega para repasar todas las tareas terminadas y pendientes. Esta transferencia inicial de conocimientos es un buen momento para responder preguntas y resolver cualquier problema final.
La documentación
contribuye a la institucionalización de estos conocimientos, es decir, a su conservación a largo plazo y a la puesta a disposición de todos los recursos prácticos necesarios para los futuros trabajos de desarrollo.
Más información
Esperamos que este artículo ofrezca un marco útil para reflexionar sobre la documentación en un mundo de desarrollo cada vez más definido por el pensamiento ágil y ajustado.
Una buena documentación es sólo una parte de las mejores prácticas para crear excelentes productos de software personalizados. Si desea obtener más información sobre el enfoque de Distillery,
póngase en contacto con nosotros aquí
.
Nos encantaría charlar sobre la creación de un proceso de desarrollo adaptado a los problemas que intenta resolver.