Documentar los aspectos de un proyecto

Introducción

A lo largo de la vida de un proyecto, este debe documentarse cuidadosamente. La documentación se gestiona en configuración (versiones), del mismo modo que el código: es parte integrante del proyecto y debe entregarse al mismo tiempo que la producción de los elementos técnicos.

Muchos departamentos informáticos disponen de procesos para asegurar la calidad y cumplen normas diseñadas para garantizar que, de un proyecto a otro, su producción de software madure y no empeore en diversos criterios. Uno de los autores de este libro ha tenido la oportunidad de certificar el nivel de madurez de varias grandes organizaciones de TI según la norma CMMI (Capability Maturity Model Integration) de ISACA, ahora en su versión 2 (ISACA cuenta con más de 140 000 miembros y profesionales certificados en más de 180 países).

Esta lista de comprobación es, en cierto modo, fruto de esa experiencia: representa los temas que hay que sacar a la luz, dirigir y documentar para prepararse a alcanzar el primero de los cinco niveles de madurez de CMMI, que, paradójicamente, es el nivel 2 (el nivel 1 indica una madurez no homogénea en los procesos del proyecto).

Si usted es «responsable funcional del proyecto», «jefe de proyecto», «responsable de método o de calidad», «business owner» o «scrum master»...

Características principales de la documentación de un proyecto informático

Los proyectos mal documentados rara vez llegan a buen puerto.

Una documentación pertinente, completa -sin ser excesiva-, garantiza una mejor coordinación entre todos los implicados en el proyecto, acelera la integración de los recién llegados y reduce el riesgo de conflictos, decepciones y malentendidos respecto a los entresijos del proyecto.

La documentación forma parte de los entregables de un proyecto tanto como su código.

Al igual que el código, la documentación debe gestionarse en términos de configuración (versionada, estructurada, etc.) y mantenerse actualizada. Los elementos de la documentación que estén obsoletos deben, como mínimo, marcarse como obsoletos, para evitar cualquier confusión entre los futuros lectores. Para gestionar la obsolescencia de los componentes de la documentación, puede, como primera aproximación, adjuntarlos a las grandes ramas gestionadas en su herramienta de control de versiones (Git, etc.).

Una cuidadosa documentación de los proyectos informáticos es esencial para garantizar su convergencia a medio plazo, su mantenimiento y su escalabilidad a largo plazo. La documentación facilita a los desarrolladores que vendrán detrás la comprensión y modificación del código fuente, y reduce...

Documentación de los aspectos clave y de los métodos de gestión de proyectos

En cuanto se habla de la oportunidad de un proyecto, las cuestiones clave asociadas guían naturalmente los debates en torno a este proyecto. Sin embargo, la comprensión de estas cuestiones evoluciona durante el proyecto, por lo que es importante mantener esta información actualizada a lo largo del proceso y recordar los supuestos en los que se basó cada decisión.

En algunas organizaciones, toda esta información se registra en un plan de proyecto que se actualiza periódicamente (puede tratarse de un sitio web o una aplicación dedicada alojada en un entorno como Gitlab, Obsidian, etc.), compartido y conocido por todos, que hace referencia a todos los demás documentos del proyecto, ya sean cuadros actualizados de seguimiento del progreso o documentos técnicos.

Arquitectura global del SI en relación con el proyecto

La arquitectura global ofrece una visión general de la arquitectura de la solución, representando sus distintos aspectos mediante diferentes vistas. Su objetivo es captar, aclarar y transmitir las decisiones de arquitectura significativas que se han tomado o se deben tomar.

La arquitectura global ofrece una visión completa de la arquitectura de la solución. Sirve de medio de comunicación entre el patrocinador y los arquitectos en relación con los puntos importantes del proyecto. La arquitectura global es el documento de referencia para las revisiones que verificarán la calidad de la arquitectura dedicada al proyecto, tanto intrínsecamente como con respecto a las normas de arquitectura de la organización.

Fichas de «Casos de uso de negocio»

Estas fichas constituyen el núcleo de su estrategia de recopilación de requisitos de los futuros usuarios de su aplicación. Establecen un vocabulario común entre usted y ellos.

Cada caso de uso de negocio debe ir acompañado de una descripción clara (puede proporcionar un diagrama de casos de uso UML).

En el ciclo ágil de gestión de proyectos, es esencial gestionar «historias» para entregar «versiones de software» que engloben «funcionalidades».

Un ejemplo típico de historia (story) de usuario es el siguiente: Como <tipo de usuario>, quiero <...> para <...>.

Dado que un caso de uso es más detallado que una historia:

Documentación para gestionar problemas y fallos

Debe existir un sistema de gestión de problemas/fallos.

Cuándo utilizar el formulario que aparece más abajo:

Ficha de Problema/Anomalía

Release note (nota que describe el contenido de una versión entregada)

Cada publicación en la fase de pruebas de aceptación o en producción debe incluir una descripción clara y concisa que incluya:

Documentación técnica moderna de las aplicaciones y los sistemas de información

Al final del proyecto o de una release importante, hay que entregar diversos códigos, scripts, etc., pero también documentación explícita que permita iniciar el ciclo de mantenimiento de la aplicación. Esta documentación se ha ido construyendo a lo largo del proyecto y forma parte intrínseca del producto que se entrega.

Hoy en día, la documentación técnica que debe elaborarse y gestionarse en una organización adopta la forma de un «producto similar a un código informático», del mismo modo que los demás componentes de la aplicación o SI. Todos estos componentes se gestionan en configuración mediante programas informáticos como Git.

Idealmente, sus componentes deben ser los siguientes: