La Documentación

Luego de muchos años de profesión como analista de sistemas , ya no me caben dudas sobre algunas cosas:

1. la documentación es sumamente importante para soportar y mantener el trabajo de un proyecto o producto
2. documentar absolutamente todo es demasiado y poco probable. En algunos casos inútil.

El reto de cualquier profesional de sistemas es el de encontrar el equilibrio sobre qué documentar, con qué grado de talle y cuándo hacerlo.

La documentación es cultural, si el profesional no documenta su obra, en mi criterio esa persona no es un profesional, es un artista hasta el primer mantenimiento y luego sin lugar a dudas un malabarista con todas las letras.

Es muy importante dejar rastro de la obra, sino la obra termina no existiendo.

Las documentación sirve para facilitar el mantenimiento y reducir las sensaciones, los conflictos y las malas interpretaciones.

Nadie lee todo y nadie sabe todo, pero existe un responsable del producto que debe tener ciertos elementos para hacer evolucionar  al producto de software desarrollado e implementado , en nuestra cultura es el analista-diseñador del sistemas.

El programador para bien o para mal tendrá siempre una visión parcial del producto total, excepto que el programador sea analista en el mismo proyecto, pero es algo que va perdiendo fuerza y sostenibilidad con los softwares cada vez más complejos.

La primera premisa básica en cualquier intervención sistémica es que debe existir un mínimo de documentación y no es el código ese mínimo, excepto que sea un prototipo, aún así lo pongo en dudas.

La documentación permite comunicar ideas, conceptos y decisiones. Alguna documentación resulta crítica para el proyecto / producto y otra resulta complementaria.

Como sea, y en cualquier metodología con la que desarrollemos nuestro  trabajo profesional, este debe quedar documentado.

Se documenta para los cambios, para la evolución del producto y para tener un punto de partida para el crecimiento del software, del sistema o de la aplicación (o como te guste llamarlo).

Se documenta para conocer el impacto.

No te olvides que los requerimientos, cambian, las reglas cambian, el cliente cambia y los trabajadores de tu organización cambian, incluso cambian los equipos, entonces tenemos buenas razones para documentar, pero no perdamos de vista que debemos documentar lo que merece la pena ser documentado. Por esto, la documentación irá evolucionando en la medida que se necesite.

Los requerimientos funcionales son necesariamente documentables; en definitiva ellos dicen que debe hacer el software.

Las reglas de negocio refieren a las normas y pautas sobre la que el software está limitado a funcionar dentro del marco de, por ejemplo, una organización.

Luego puede aparecer un set de modelos interesantes que serán más relevantes en ciertos proyectos que otros. En mi opinión es visión del profesional expandir la documentación, o bien, retraerla en la medida que así lo vea necesario.

Es importante pensar en un mínimo y en la calidad. Generar documentación que nadie entiende o nadie le resulta de utilidad es una pérdida de dinero.

La prueba ataca

La prueba ha evolucionado; pasando de ser vista y tratada como arte hasta un visión de proceso.

De la nada y, observando la poca calidad de la entrega de un producto de software, la prueba se transformó en el primer instrumento de control, luego se hizo fase, más tarde un proceso que atravesaría todo el ciclo de vida de proyecto primero y de producto después.

Sin embargo, en el ADN de los profesionales de sistemas, la prueba continúa siendo maltratada y demonizada.
La prueba es un trabajo para principiantes, es poco relevante, es un trabajo "menor". Si un profesional piensa esto, tendrá que volver a re-pensarse.  Fea la actitud.
La prueba no es una actividad de segunda mano. Veamos que con los años se ha transformado en un proceso, a pesar de los profesionales, en segundo plano ha continuado creciendo a pesar de nosotros mismos, los profesionales de sistemas. Algo tiene que haber.
Me gusta ver la prueba como una guía para una planta que está creciendo. Me gusta ver a las personas que realizan esa función como "GUARDIANES de la calidad"
El probador, tester o responsable de ejecución de la prueba tiene una función vital. Asegurarse de encontrar errores antes que los encuentre el cliente en PRODUCCION.

La prueba es inevitable. Sin prueba no hay calidad y los errores aparecerán por docenas (para ser humilde) .

La prueba que no encuentra errores es una prueba deficiente. El responsable de prueba ( y no solo de ejecución) debe encontrar errores. Es su fin.

Con el tiempo se asimiló que cuanto antes se encuentran errores, más fáciles son de corregir.
También se observó que los errores no solo están en el código, sino que en el diseño, en el análisis, en la definición del producto y hasta en la misma prueba. Este pensamiento hizo que la prueba atravesara a todo el ciclo de vida del producto.

Otro mito interesante que surge en que la prueba es sentarse y ejecutar un programa y, ver que onda,  o sea, onda veo si encuentro error. Este es otro error.
La prueba debe ser pensada, por esto, algunos autores definen al proceso como:

Definir que probar
Diseñar la prueba
Ejecutar la prueba
Corregir los errores

Estas super actividades son subprocesos en si mismos, requieren diferentes roles y no refieren a sentarse y probar.
Así que ahora además tendremos que pensar que si la prueba está al menos involucrando estas cuestiones entonces se trata de algo más sentarse frente a un equipo, correr un programa y fijarse si se encuentra un error.

El proceso de prueba se irá "desarrollando" a lo largo del proyecto de desarrollo, no cabe de duda. Es un proceso continuo.

¿Por qué los programadores reniegan de los probadores?
Ponete a pensar que un programador, genera una “obra de arte” y el probador es el crítico de la obra de arte. Además si bien el probador realiza una crítica constructiva o regenerativa; el ego del programador le impide verla. Claro, esto también está cambiando; es CULTURAL.
Incluso algunas organizaciones contribuyen a la desmejora CULTURAL considerando el valor hora de la prueba de menor rango. Otro pensamiento erróneo instalado.

Igualmente convengamos que la ejecución de la prueba no es una actividad "FELIZ", pero habrá que buscarle la vuelta.
La actividad requiere de un perfil, me refiero a la ejecución, metódico y estructurado, que permita ver que su trabajo engrandece la calidad del producto. Una persona con espíritu crítico pero no soberbio. Al fin y al cabo cuando el probador encuentre el error, nadie podrá negarlo.
El probador debe tener las libertades para proponer nuevas miradas sobre la prueba en cualquiera de sus partes; el probador es el usuario de lo que se prueba.
El subproceso que define que probar necesita del conocimiento del sistema que se desarrolla, el diseño de la prueba requiere de algún conocimiento del negocio.
El área de control de calidad tiene la responsabilidad de definir buenas prácticas y lineamientos de trabajo. La Gerencia debe sponsorear la calidad sosteniendo la prueba a pesar del stress, los líderes de proyecto son artífices de sostener la prueba a pesar del stress.
Las auditorías internas y externas, las revisiones de pares son otras formas de controlar la calidad, son otra forma de probar.
Es muy significativa la imagen de la bola de nieve que comienza pequeña en la punta de la montaña pero se es impresionantemente grande al llegar al pie de la misma.
Un requerimiento mal encarado al principio produce ese efecto en el final del desarrollo de un producto. Probar lo antes posible es una premisa de este proceso continuo.
Por lo mencionado, es importante validar los requerimientos desde su concepción.

La prueba falla cuando no se encuentran errores. Ojo siempre hay errores algunos aun subyacentes, pero están.
Cuando una prueba no es eficiente deben encontrarse variantes.

El secreto de las herramientas. Un secreto gritado a voces.

Todos sabemos que las herramientas ayudan a los profesionales de todos las áreas en su trabajo.

Algunas herramientas son más completas, otras más eficaces, algunas facilitan el trabajo, otras permiten hacer el trabajo más rápido. Como sea, sin herramientas muchos trabajos no se podrían realizar.

Clavar un clavo sin un martillo o ajustar los tornillo de una rueda sin al menos un llave CRUZ, serían tareas demasiado complejas, difíciles o imposibles de ejecutar, incluso para profesionales avezados.

La herramienta sola no es nada, dependemos de la habilidad de quien la usa, la herramienta debe estar en manos de un trabajador (worker); él es quien cambia el destino de una batalla.

Tener la herramienta sin el worker sólo te hace poderoso en una mesa, durante una charla, pero no en el campo de batalla.

En el área de conocimiento de software las personas y las herramientas son elementos importantes de la calidad, diría que la interacción producida entre la persona y la herramienta es mucho más importantes que los elementos por separado. La persona tiene el conocimiento y el herramienta el don de facilitarlo. El conjunto es un simbiosis fundamental.

No es concebible desarrollar software sin ambos elementos, mucho menos con calidad; pero recuerda el verdadero secreto no es la herramienta sino la persona que la usa.

De este modo comprenderás que si pones tu éxito sólo en las herramientas te estarás equivocando y si solo lo ponés en las personas será insuficiente deberás realizar una mezcla útil.

Tampoco puedes esperar que la relación se base en tomar un individuo  y darle una herramienta. El individuo debe conocer y saber hacer con la herramienta.

El éxito de la relación lo consigues cuando el profesional sabe usar la herramienta y tiene arraigado los conceptos que le permiten volverla más eficaz.

De nada sirve que se tenga una herramienta para modelar diagramas de actividad, si el profesional no conoce sobre  diagramas de actividad. Puede que haga un dibujo con componentes de diagrama de actividad, pero ¿estará haciendo un diagrama de actividad?

Tareas de Análisis. Características

Introducción

Sin importar la forma que le des al proyecto, ni cual ciclo de vida tomes como base; un proyecto de desarrollo siempre tendrá las tareas de análisis, diseño, codificación y prueba. Son tareas básicas.

Puedes tener motivos y razones super convincentes para negar una actividad básica. Puede suceder que utilices un generador de código y la programación se simplifique, estamos de acuerdo; se consume menos esfuerzo; pero la tarea existe.

La forma que adquiera el proyecto no es nuestro centro. Algunas personas prefieren invisivilizar ciertas tareas, diciendo que no hay diseño, o que no se realiza la prueba. No importa lo que digan. Si no explicitas la prueba te está faltando o esta oculta bajo otro título.

No se debería pasar un producto de software al cliente sin hacer pruebas; no debería comenzarse la programación sin un diseño mínimo. Lo que no se haga donde corresponde quedará en manos del que sigue en un proceso de desarrollo. Si el que sigue es el cliente, bueno es tu riesgo.

Luego según la cultura de tu empresa, de tu equipo o tu región realizarás proyectos en donde algún tipo de tarea destaque sobre otra; siendo, por ejemplo, las pruebas mínimas y de un solo tipo.

En este blog trataremos las características de las actividades básicas. Nuestro centro es la tarea de análisis.

Objetivo

Explicitar las características generales de la tarea básicas de análisis dentro del marco de un proyecto.

Análisis

El análisis es un tarea que puede especializarse en muchas subtareas y muchas formas; pero una característica casi natural es que es una actividad netamente iterativa y cognitiva; estas son las características que la destacan.

Un analista realiza un conjunto de acciones para comprender el sistema bajo estudio, volviendo y una otra vez sobre tareas que parecían terminadas, pero no lo están.

Característica 1. Materialización del producto de trabajo.
Un analista realiza una entrevista y comienza el análisis; como consecuencia descubre omisiones, falta de información y otras yerbas; el resultado volver a realizar una entrevista.

El párrafo anterior muestra que avance pero no produje nuevos artefactos; comencé con una entrevista y por el estado del arte regresé por una nueva entrevista. Es cierto que he avanzado pero no en forma lineal sino iterativa. Continuo relevando el sistema pero con otro conocimiento inicial.

Luego pasaron 2 días y el analista tiene más dudas que productos de trabajo elaborados. Esto es y debe considerarse completamente natural. Lo importante no es documentar el sistema, sino comprenderlo y luego documentar la comprensión. Como sea, pueden pasar varios días de borradores, bosquejos y anotaciones; pero ninguna producción concreta.

Es importante tener presente está característica pues, en una tarea de análisis de una semana es probable que comencemos a ver producción a partir del día 3 o 4; esto es aproximadamente en el 50% del esfuerzo ejecutado. En una tarea de análisis de 15 días se puede comenzar a ver la producción de la documentación cuando la tarea lleva un 20 %, pero no será cerrado hasta un 90%  avanzada su ejecución.

Estas ideas son cuestionables; en el sentido que las personas tienden a tener distintas estrategias de trabajo. Algunos profesionales crean al principio todos los documentos que saben que usarán, lo cual puede parecer que se han desarrollado muchísimos artefactos; pero ninguno está ni siquiera completado con contenido significativo; ver muchos documentos realizados es una falsa presunción de avance en muchos casos.

Característica 2. Cantidad de productos de trabajo
El análisis es una de esas tareas que crea un número interesante de artefactos: listas de requerimientos, reglas de negocio, maquinas de estado, modelos del dominio, tabla de actores, diccionarios de datos.

Mientras que en otro tipo de negocios cada actividad produce un producto de trabajo ( o 2), en el análisis se producen al menos una decena. Algunos ni siquiera estaban planeados...grrrr.

Esta cantidad no es sinónimo de tamaño. Hacer 10 productos de trabajo sobre un total de 20 no significa que se ha realizado el 50 % de la tarea. Si pensabas eso, pues lo siento no es así.

Característica 3. Evolución de productos de trabajo
El análisis tiene eso viste, pensás que estás terminando un producto de trabajo y cuando comenzás (o continuás con) otro; descubrís que estabas errado.

Ey!!!!, no debería decir que la tarea de análisis es una tarea compleja; pues bien lo es.

Ahora bien, la tarea de analisis es de estas tareas que cuando más crees que avanzaste, más seguro estás que no; luego finalmente como por arte de magia, se estabiliza y todo fluye.

Aquí se presentan algunos ejemplos que muestran la evoluciones típicas en la producción de artefactos / productos de trabajo:
Ejemplo 1

Este podría decirse que es el más natural, escasos o nulos artefactos al comienzo de la actividad / tarea y luego de superado el 50 % un crecimiento continuo.
Observe que no se indica el tiempo en números es simplemente una idea de evolución teórica.
Ejemplo 2

En este caso se intenta mostrar que al principio no existen artefactos, pero luego comienza a aparecer hasta alcanzar la totalidad de artefactos que debían crearse. En este fenómeno el analista estuvo un tiempo importante realizando procesos mentales hasta que decidió que el trabajo ya podría comenzar a materializarse. Tiene ciertas semejanzas con el ejemplo anterior.

Ejemplo 3

Aquí se intenta mostrar que se producen una serie de artefactos al principio y el resto al final.
Este es el caso del analista se apresura a crear artefactos pero no completará mucho hasta acercarse al final.

Ejemplo 4

Este caso no es real en el análisis. Aquí se muestra que la producción de artefactos es continua y constante, nada más irreal en la tarea de análisis.

Claro está que no son las únicas evoluciones, pero la intensión es simplemente ejemplificar la idea.

Don, el analista

Don es un analista, quizás  es un analista tradicional. Su cabello está prolijamente recortado, trabaja en una empresa mediana, aspira a tener su negocio, pero siempre se dice así mismo que no es el momento.

Don es un entusiasta de hablar con la gente sobre todo si se trata de sistemas, incluso más que el fútbol.

Él no piensa mucho en su edad, claro es joven, y tiene toda la energía para derrotar los demonios del mundo, sin embargo, hoy está más pensativo que de costumbre.

Hace varios años que hace análisis, pero ahora se presenta un reto, algo distinto.

No se trata de documentar lo que escucha, se trata de interpretar necesidades y problemas. Don reflexiona y sabe que siempre lo ha hecho, pero esta vez es diferente pues está consciente. Antes solo lo hacía.

El cliente parece no tener mucho tiempo y no tener muchas ganas de atenderlo, piensa que Don no lo entiende y se pregunta si hace bien en dedicar tanto tiempo. No duda de la capacidad de Don, duda de la utilidad de las reuniones.

El cliente tiene la sensación que Don se desvía del eje y por momentos cree entender que entiende hacia donde Don apunta.

Don sabe que el cliente está intranquilo, pero él está ocupado pensando en sus descubrimientos durante la entrevista.

Don se pregunta si servirá realizar una aclaración sobre lo que ve; o continuar adelante.

El cliente mira el reloj, Don lo decide, ya es tiempo de terminar la entrevista.

Requerimientos versus casos de uso

Lo que voy a comentar puede no ser una novedad, pero es importante no perderlo de vista.
Un caso de uso con alcance sistema es una descripción de un conjunto de requerimientos organizados y pensados para ayudar a cumplir las metas de un actor. Si necesitas especificar requerimientos te sirven los casos de uso de alcance sistema.

Las definiciones enunciadas son parciales y mejorables, aunque espero te ayuden a entender hacia donde vamos. Como se dice por ahí: "los casos de uso son requerimientos y esencialmente de requerimientos funcionales"

Hoy en día no dudo en utilizar casos de uso como un método para especificar requerimientos y luego ir desarrollándolos (o completándolos).

Los casos de uso vinieron a cubrir ciertas necesidades de especificación y trabajo con los requerimientos, abandonando o dejando de lado la lista de requerimientos; pero la lista de requerimientos no ha muerto.

Hoy los casos de uso se han transformado en los favoritos de los analistas en sistemas de información, teniendo sobradas razones para serlo, pero la lista de requerimientos se sostendrá por mucho tiempo.

Los casos más significativos en donde la lista de reqeurimientos suele ser mejor especificación que los casos de uso se ven en:
no hay workflow, cuando los procesos no pueden precisar secuencias, cuando se trata de una serie de sub-características que debe poseer una aplicación, o cuando los requerimientos no funcionales son la razón de la aplicación, entonces allí la lista de requerimientos domina el territorio.

Pero atención no tienes que decidirte por una, puedes elegir cual usar según el momento, y por supuesto existirán variantes.

Ejemplo 1
Suponga que un actor, el recepcionista de una organización, en su trabajo diario debe escribir gran cantidad de texto sobre campos VARCHAR. El recepcionista en pos de mejorar su trabajo y mejorar el resultado solicita poder copiar y pegar texto, agregar negritas, itálicas, subrayados y cambios de tamaño.
Este tipo de requerimientos  o características es  mejor especificarlos en listas de requerimientos. Intentar organizar estos requerimientos bajo la imagen de un caso de uso no sirve.

Ejemplo 2
Un líder de proyecto indica que desea crear un proyecto y,  para ello define las tareas, luego los recursos, asigna recursos a tareas, las tareas a recursos, borra tareas, cambia recursos, indica costos, a veces decide calcularlos, otras no.
Este caso presenta otra complejidad. Aquí armar un caso de uso  presenta múltiples escenarios y se torna muy engorroso plantearlos a todos. Es más práctico una lista de requerimientos.

Debo reconocer que prefiero los casos de uso a la lista de requerimientos, pero no siempre es aplicable.
Es importante decidir cuando conviene una cosa y cuando otra.

Transformado requerimientos no verificables en verificables

Un cliente llama al teléfono temprano en la mañana del lunes y dice:

-- No te olvides que el "programa" debe tener una mayor seguridad.

Desafortunadamente colgó antes de poder reaccionar o re-preguntarle.
¿Qué habrá querido decir con mayor seguridad?

Cuando ocurre un caso como este, lo mejor es esperar, no adelantarse y reconocer que se debe investigar un poco más.

Pensemos:

• Restringir el acceso a la aplicación a usuarios autorizados.
• Establecer permisos y roles para el acceso a la funcionalidad.
• Encriptar los datos de la base de datos
• Establecer un control de accesos realizados por los usuarios

Adelantemos el tiempo, imaginemos e idealicemos que sucedió realmente:

Se le pregunta al cliente que quiso significar con mayor seguridad. El cliente comenta:

-- Durante años quise tener una aplicación, pero ahora tengo miedo que alguien entre por internet y me robe los datos.

Al comprender mejor, se entienden mejor los requerimientos. Se puede afirmar que mayor seguridad es: impedir el acceso por internet a los datos de la organización por personas no autorizadas.

Por supuesto y sin dudarlo esto debe quedar registrado en algún documento, más tarde se deberá volver sobre el requerimiento para asegurar su cumplimiento. Si es posible demostrar que no es posible acceder a los datos de la organización a través de internet, entonces el requerimientos será verificable.

Para determinar que se cumple con el requerimiento debe poder ser verificado. Dicho de otro modo, debe ser posible demostrar que existe y se ajusta a la especifificación. Un requerimiento no verificable trae problemas siempre.

Algunos ejemplos malos

1. La aplicación debe ser rápida. --> ¿qué es rápido?
2. Las interfaces de usuario deben ser fáciles.  --> ¿qué es fácil?
3. El código debe ser mantenible.--> ¿qués mantenible?

Ejemplos mejorados y verificables

1. Las respuestas de la aplicación deben ser menores a 3 segundos en el 80% de los casos en horario diurno. Nota: el horario abarca desde las 9:00 am y hasta las 4:00 pm
2. Las interfaces de usuario deben tener homogeneidad presentando los títulos, datos y acciones en las posiciones definidas en minuta 05/12/2014. Ver estándar versión 1.04 de IU.
3. El código usa una sólo instrucción por línea, las variables locales comienzan con el prefijo l_, las variables globales con el prefijo g_.