La documentación técnica en el desarrollo de software y sus modelos

Por definición, la documentación técnica es la forma idónea que como profesionales del desarrollo de software debemos emplear para compartir la información evidenciada en cada una de las etapas de la creación del software y sus pormenotes. En un sentido práctico, esta documentación es un registro explícito de todos los eventos o procesos involucrados a lo largo del Ciclo de Vida del Desarrollo de Software (SDLC)

Por ende, en este artículo nos hemos propuesto abordar esta temática de forma tal que influya a los programadores a escribir una mejor documentación técnica para sus futuros desarrollos de software, debido a que en esta se establecen las mejores prácticas para su uso y mantenimiento.

Aun así, para los desarrolladores escribir documentación es un trabajo que resulta incómodo pero sabemos de primera mano que leer código con una documentación deficiente, o en el peor de los casos sin documentación alguna, es inadmisible. En consecuencia, queda claro que al redactar la documentación de un producto lo estamos haciendo para los futuros desarrolladores que interactuarán con dicho producto, no para nosotros ni el equipo que intervino en su creación.

Entonces, partiendo de la premisa de que todos los productos de software necesitan documentación técnica sin importar su complejidad o el tamaño del equipo involucrado en su desarrollo, conozcamos sus alcances y los tipos de documentación existentes.

Aspectos que aborda la documentación técnica

El objetivo de la documentación técnica es informar sobre los pormenores que de acuerdo a nuestro rol precisamos conocer para comprender e interactuar con el producto. Esta se crea a partir de las fases contempladas en el ciclo de vida del desarrollo de software (SDLC) o las etapas del desarrollo de software, las cuales son:

Planificación

En esta etapa, de acuerdo a la investigación de mercado se determina la viabilidad del proyecto, sus riesgos asociados, sus costes y qué funciones y servicios darán satisfacción al público objetivo.

Análisis

Esta fase es clave de cara a los requerimientos y necesidades de los usuarios y cómo los detalles y especificaciones técnicas entregarán el valor esperado por estos usuarios. Este proceso se ejecuta en un marco de trabajo claro en el que las responsabilidades, las entregas y las pruebas están ancladas a un calendario pertinente.

Diseño

Esta etapa es completamente dedicada a diseñadores, arquitectos y programadores de aplicaciones quienes tienen la responsabilidad de estudiar opciones de implementación para estructurar y desarrollar el mejor software posible. Esta fase normalmente es iterativa debido a que es preciso depurar y refinar los planos del producto antes de tener un diseño definitivo.

Desarrollo e implementación

Partiendo de una elección correcta de herramientas como lo son los entornos de programación apropiados, lenguajes convenientes, lógicas sólidas y formatos globales, el código empieza a desarrollarse por módulos, los cuales serán probados y aprobados hasta terminar la aplicación.

Pruebas

Esta es una fase de auditoría y corrección de una versión estable de la aplicación. En el ámbito del desarrollo se dice que una prueba es exitosa cuando se detectan errores, así que, aquí es donde la aplicación dará sus primeros pasos y será corregida de manera iterativa antes de que el usuario final pueda servirse de ella íntegramente.

Implementación y mantenimiento

Llegando al final del ciclo, el departamento de TI tiene como responsabilidad dar de alta la aplicación, monitorearla, mantenerla y conseguir que su funcionalidad se mantenga impecable, con el objetivo de garantizar el mejor rendimiento a todos sus usuarios. En esta etapa sin duda también debe existir el análisis introspectivo donde sean consideradas futuras actualizaciones y mejoras.

Tipos de documentación técnica

La documentación técnica está dirigida a diferentes audiencias de acuerdo a su relación con el producto tanto si diseñan, crean, revisan, corrigen o simplemente utilizan el software. Estos son sus tipos:

Documento de requisitos del producto

En este se debe registrar toda la información sobre la funcionalidad de la aplicación teniendo en cuenta aspectos comerciales, experiencias de los usuarios, casos de uso, entre otros. Además, es imperativo dejar en claro el propósito, las funcionalidades, el comportamiento y el mantenimiento del producto final.

Modelo

• Funciones y responsabilidades
• Metas y objetivos
• Misión
• Experiencias y justificación
• Diseño e interacción
• Dudas
• Tareas a resolver

Documento de arquitectura de software

Este documento puntualiza y describe las decisiones arquitectónicas en torno a la infraestructura de la aplicación. Aquí se describe la construcción del producto, con el objetivo de poder visualizar y comunicar los escenarios posibles.

Modelo

• Resumen y antecedentes
• Principios de diseño
• Experiencias de usuarios y objetivos comerciales
• Explicación de la solución
• Hitos

Documento de diseño UX

Para este documento se debe hacer una investigación o benchmarking relacionados a la aplicación esperada para poder crear sus prototipos, realizar pruebas de usabilidad y ajustes.

Modelo

• Usuarios
• Escenarios
• Mapa de usuario
• Guía de estilo UX

Documento de código fuente

Es claro que un buen código no necesita documentación, pero también es cierto que como programadores tenemos estilos y enfoques diferentes para crear soluciones. Por ende, esta diversidad necesita de un marco común bajo el cual podamos entendernos claramente: la documentación del software.

Modelo

• Marcos generales
• Código comentado
• Tipos de enlace de datos
• Patrón de diseño y creación
• Medidas de seguridad
• Adicionales

Documento del proceso

En este documento se debe detallar cronológicamente el plan de trabajo, los responsables, sus fechas de entrega y las expectativas de todo el desarrollo. La documentación del proceso promoverá la comunicación y la transparencia entre miembros y departamentos involucrados.

Modelo

• Planes, estimaciones y cronogramas
• Reportes
• Documentos y manuales de trabajo
• Objetivos y mejores prácticas

Documento de calidad

El objetivo detrás de esta documentación radica en abordar, monitorear y ejecutar los desarrollos y las pruebas necesarias para lograr controlar y garantizar la calidad del producto tecnológico. Estas pruebas por lo general son muy especificas y cada una corresponde a un determinado objetivo dentro de la operación o ejecución de la aplicación.

Modelo

• Plan de gestión de calidad
• Estrategia de prueba
• Plan de prueba
• Especificaciones
• Checklist

Documento del usuario final

Esta etapa documentada está dedicada a explicar de forma dinámica como el producto creado puede resolver el problema que el usuario final necesita superar de la manera más breve y sencilla posible.

Modelo

• Guía de uso rápido
• Manual completo
• Guía de solución de problemas
• Preguntas frecuentes

Documento del administrador del sistema

Aquí es preciso detallar aspectos esenciales que determinan la funcionalidad y la disponibilidad de la aplicación. Estos normalmente cubren la instalación del producto y las actualizaciones propias y periféricas para que el administrador pueda mantener la aplicación en funcionamiento y sus usuarios servirse de ella sin contratiempos.

Modelo

• Descripción de funcionalidades
• Guía de administración
• Solución de problemas
• Checklist -Preguntas frecuentes

En términos generales, bajo el marco de la ingeniería, la documentación técnica aborda todo tipo de información evidenciada en los ciclos de desarrollo que atraviesan los todos productos de software. Por ende, el seguimiento y la supervisión son herramientas valiosas no solo para la creación de la documentación sino para la mejora de la calidad de la solución de software.

En consecuencia, cada vez que tu empresa aborde un proyecto de desarrollo necesitará asegurar una ejecución impecable de lo anterior, esto solo podrá lograrse con el apoyo de un equipo tecnológico experto y consolidado. Para respaldarte en esta labor, en DreamCode hemos conformado un gran equipo de especialistas en el desarrollo tanto de software como de la documentación que este requiere, trabajando bajo la premisa de entregar a todos nuestros clientes herramientas empresariales de alto valor e impacto comercial. Conoce más aquí