Con el objetivo de consolidar lo aprendido acerca de documentación de software, se ha creado este repositorio como manual de referencia para futuros proyectos.

La documentación de software es un conjunto de documentos que describen el sistema desde múltiples perspectivas.

Su propósito es facilitar el uso, mantenimiento y desarrollo del software.

Los usuarios pueden usar la documentación para aprender cómo usar el sistema, mientras que los desarrolladores pueden usarla para comprender el diseño o la implementación del sistema.

La documentación de software es importante porque:

• Mejora la calidad del software: La documentación ayuda a evitar errores, inconsistencias y ambigüedades en las funcionalidades del sistema, así como a facilitar la detección y corrección de defectos.

• Facilita la comunicación y colaboración: La documentación permite a los diferentes actores involucrados en el proyecto (clientes, usuarios, devs, testers, etc.) entender los requisitos, funcionalidades y limitaciones del sistema.

• Reduce el costo y el tiempo de desarrollo: La documentación ayuda a planificar, organizar y gestionar el proyecto, así como a reutilizar código o componentes existentes. También evita la pérdida de información o conocimiento cuando se produce un cambio de personal o de tecnología.

Existen diferentes tipos de documentación de software. Con el fin de facilitar su comprensión, personalmente los clasifico según tres dimensiones:

• El elemento documentado: La primera dimensión se refiere al elemento en sí. Por ejemplo: un requisito, un procedimiento, código, etc.

• El perfil del lector: La segunda dimensión corresponde a quién va dirigido el documento. Por ejemplo: desarrolladores, usuarios, analistas, etc.

• El propósito de la documentación: La tercera dimensión es el tipo de información que se desea comunicar. Por ejemplo: descripción actual del sistema, especificación de lo que se implementará, etc.

Esto se explica detalladamente aquí.

Los metadatos son datos acerca del documento en sí.

Para la documentación de software se recomienda incluir los siguientes metadatos: Lista de metadatos

Más conceptual

• Visión (vision): Es la declaración previsora de lo que se espera del proyecto en el futuro.

• Épica (epic): Es un grupo de funcionalidades o características que responden a una misma necesidad que el sistema debe satisfacer.

• Característica (feature): Es una funcionalidad definida por un conjunto de interacciones.

• Caso de uso (user story): Es la descripción de una interacción con sistema desde la perspectiva del usuario.

• Implementación (implementation): Es la descripción técnica de cómo se implementó una funcionalidad.

Más técnico

Ejemplo:

Software de gestión para una bodega de productos (Visión)

• Control de inventario (Épica)
  • Gestión de proveedores (Característica)
  • Programación de Alertas (Característica)
  • Reportes de inventario (Característica)
  • Gestión de productos (Característica)
    • Ingresar producto con rol de almacenista (Caso de uso)
      • Algoritmo de ingreso de producto (Implementación)

Las Fases del Desarrollo son los pasos que se siguen al realizar un proyecto de documentación de software.

Estas fases son:

• Preámbulo: El primer paso del proceso de documentación es conocer la metainformación del trabajo que se debe realizar.

• Exploración: Durante la exploración debes comprender el contexto del sistema y determinar los procedimientos actuales utilizados por los usuarios.

• Análisis: El análisis de requerimientos implica identificar las necesidades de los usuarios y los criterios de aceptación para la solución que se proponga.

• Diseño: Para el diseño de la solución debes presentar diferentes alternativas como solución a la necesidad y seleccionar la más adecuada.

• Implementación: Haz seguimiento al desarrollo y agrega textos técnicos acerca de la implementación.

• Entrega: Agrega detalles, notas y advertencias finales. Entrega la solución creada con la documentación correspondiente.

Abstract

• Página inicial
• Prefacio
• Glosario

Documentación no técnica (La documentación no técnica son descripciones e instrucciones claras para un público que puede no estar familiarizado con los detalles del sistema o los procesos.)

• Anexos
• Reuniones
• Procesos
• Requerimientos
• Casos de uso
• Plan de pruebas
• Notas y advertencias acerca de las decisiones tomadas

Documentación técnica (La documentación técnica describe y explica aspectos tecnológicos, características y funciones del software, como su arquitectura, diseño, algoritmos o APIs, con el objetivo de facilitar su comprensión, mantenimiento y colaboración entre desarrolladores.)

• Topología
• Componentes de software
• Diagramas de bases de datos
• Especificación de APIs
• Algoritmos de servicios
• Lista de nuevos permisos
• Tareas y actividades

Documentación de entrega (La documentación de entrega va dirigidada a los usuarios finales del sistema)

• Manual de instalación
• Manual de uso
• Registro de cambios

• Flujo de trabajo

• Navegación y estructura

• Licencias

• Referencias

• Documentación basada en texto

  • listas
  • tablas
  • código