Documentación del Software¶

1. ¿Por qué es Importante la Documentación?¶

La documentación es un aspecto crucial en el desarrollo de software que:

Comunica: Explica el funcionamiento a desarrolladores y usuarios
Facilita uso: Ayuda a usuarios a utilizar el software
Facilita mantenimiento: Permite que otros desarrolladores entiendan el código
Asegura calidad: Documente requisitos, decisiones, riesgos
Reduce dependencia: No depender de una sola persona que "sabe cómo funciona"
Escala el conocimiento: El conocimiento se comparte y persiste

Sin documentación:¶

Solo el autor original entiende el código
Cuando se va, el conocimiento se va con él
Cambios se hacen de forma arriesgada (sin entender impacto)
Nuevos desarrolladores tardan meses en entender
Usuarios no saben cómo usar la aplicación

Con documentación:¶

Código entendible para cualquiera
Decisiones quedan registradas
Nuevos desarrolladores se integran rápido
Usuarios saben qué hacer
Cambios seguros y con contexto

2. Tipos de Documentación¶

2.1 Documentación Técnica¶

Destinada a: Desarrolladores, arquitectos, DevOps

Manuales Técnicos¶

Incluyen:

Arquitectura del software (diagrama general)
Configuración del entorno de desarrollo
Configuración del entorno de producción
Guías para que nuevos desarrolladores contribuyan
Procesos de build, deploy, testing

Ejemplo de estructura:

MANUAL TÉCNICO - Sistema de Gestión de Tareas

1. ARQUITECTURA
   - Diagrama de componentes
   - Módulos principales
   - Flujo de datos

2. CONFIGURACIÓN DEL DESARROLLO
   - Requisitos (Java 11+, Maven 3.6+, PostgreSQL 12)
   - Clonar repositorio
   - Instalar dependencias
   - Configurar base de datos local
   - Ejecutar tests

3. GUÍA DE CONTRIBUCIÓN
   - Nombrado de ramas
   - Proceso de commit
   - Requisitos de código (tests, coverage)
   - Proceso de pull request
   - Code review checklist

4. DESPLIEGUE
   - Proceso de despliegue a staging
   - Proceso de despliegue a producción
   - Rollback procedures
   - Monitoreo

Especificaciones de Diseño¶

Describen:

Estructura del software (clases, interfaces, módulos)
Diagramas UML (clases, secuencias, estados)
Decisiones de diseño y por qué
Patrones de diseño usados
Consideraciones de rendimiento

Ejemplo:

ESPECIFICACIÓN DE DISEÑO - Módulo de Autenticación

DIAGRAMA DE CLASES:
    Usuario
    ├─ email: String
    ├─ passwordHash: String
    ├─ verificarPassword(String): boolean
    └─ cambiarPassword(String): void

FLUJO DE AUTENTICACIÓN:
    1. Usuario ingresa credenciales
    2. Sistema busca usuario en BD
    3. Compara hash de password
    4. Si match, crea JWT token
    5. Token se envía al cliente

DECISIONES DE DISEÑO:
- Se usa JWT en lugar de sesiones por:
  * Escalabilidad (sin estado en servidor)
  * Compatible con arquitectura de microservicios
  * Fácil de usar en aplicaciones móviles

2.2 Documentación de Usuario¶

Destinada a: Usuarios finales, administradores, soporte

Manuales de Usuario¶

Contienen:

Cómo instalar el software
Cómo usar las funcionalidades principales
Guías paso a paso
Resolución de problemas comunes
Preguntas frecuentes (FAQs)

Ejemplo de manual de usuario:

MANUAL DE USUARIO - Sistema de Gestión de Tareas

INSTALACIÓN:
    Paso 1: Descargar el instalador desde www.ejemplo.com
    Paso 2: Ejecutar el instalador
    Paso 3: Seguir el asistente
    Paso 4: Reiniciar el ordenador

CREAR UNA NUEVA TAREA:
    Paso 1: Hacer clic en el botón "Nueva Tarea"
    Paso 2: Ingresar el nombre de la tarea
    Paso 3: (Opcional) Seleccionar fecha de vencimiento
    Paso 4: (Opcional) Asignar a un usuario
    Paso 5: Hacer clic en "Guardar"

PREGUNTAS FRECUENTES:
    P: ¿Cómo cambio mi contraseña?
    R: Ve a Configuración > Cuenta > Cambiar Contraseña

    P: ¿Puedo compartir tareas con otros usuarios?
    R: Sí, edita la tarea y agrega usuarios...

Tutoriales y Guías¶

Instrucciones paso a paso para tareas comunes
Videos tutoriales
Casos de uso reales
Dirigidos a usuarios sin experiencia técnica

2.3 Documentación en el Código¶

Ubicación: Dentro del código fuente mismo

Comentarios en el Código¶

Sirven para:

Explicar por qué se hace algo (no qué - eso es el código)
Advertencias sobre efectos secundarios
Explicar decisiones de diseño importantes
Notas sobre partes complejas

Buen comentario (explica el por qué):

// Usamos caché aquí porque esta operación es costosa (3 segundos)
// sin caché, el dashboard sería demasiado lento
// Se invalida cada 5 minutos o cuando hay cambios
Map<String, DashboardData> cache = new HashMap<>();

Mal comentario (explica lo obvio):

// Suma dos números
public int suma(int a, int b) {
    return a + b;  // El código ya lo dice
}

Documentación de API (Javadoc)¶

Documentación de clases, métodos, parámetros
Generada automáticamente a partir de comentarios especiales
Accesible como referencia web

Ejemplo:

/**
 * Calcula el total de un pedido aplicando descuentos.
 * 
 * @param pedido El pedido a procesar (no puede ser null)
 * @param cliente El cliente que hace el pedido
 * @return El total final después de descuentos
 * @throws IllegalArgumentException si el pedido es null
 * 
 * @see Descuento#aplicar(double)
 */
public double calcularTotal(Pedido pedido, Cliente cliente) {
    if (pedido == null) {
        throw new IllegalArgumentException("Pedido no puede ser null");
    }
    // Implementación...
}

Etiquetas Javadoc comunes:

@param nombreParam    - Describe un parámetro
@return               - Describe el valor de retorno
@throws ExceptionType - Excepciones que puede lanzar
@see OtraClase        - Referencia cruzada
@author NombreAutor   - Quién escribió esto
@deprecated           - Indica que está obsoleto
@since version1.0     - Desde qué versión existe

3. Principios de Buena Documentación¶

3.1 Claridad¶

¿Qué significa?: Usar lenguaje simple y directo

Cómo lograrlo:

Evitar jerga técnica innecesaria
Explicar términos técnicos cuando sea necesario
Usar frases cortas y simples
Estructurar con títulos y secciones
Ejemplos donde sea posible

Ejemplo MALO (confuso):

El subsistema implementa una arquitectura hexagonal
mediante inyección de dependencias invirtiendo el
control y aplicando el patrón SOLID.

Ejemplo BUENO (claro):

La aplicación está organizada en capas:
1. Controladores: Reciben solicitudes HTTP
2. Servicios: Contienen la lógica de negocio
3. Repositorios: Acceden a la base de datos

Esto permite cambiar la BD sin afectar la lógica de negocio.

3.2 Concisión¶

¿Qué significa?: Ser breve, sin información innecesaria

Cómo lograrlo:

Incluir solo información relevante
Ir al punto sin rodeos
Evitar repeticiones
Usar listas en lugar de párrafos largos

Ejemplo MALO (demasiado largo):

Para cambiar de contraseña, primero debes acceder al
menú de configuración que está en la esquina superior
derecha de la pantalla. Una vez allí, buscarás una
opción que dice "Cuenta" o "Perfil", dependiendo de
la versión del software que estés usando. Luego...

Ejemplo BUENO (conciso):

Para cambiar contraseña:
1. Configuración (esquina superior derecha)
2. Cuenta > Cambiar Contraseña
3. Ingresa contraseña actual y nueva
4. Guardar

3.3 Consistencia¶

¿Qué significa?: Mismo estilo, formato y términos en toda la documentación

Cómo lograrlo:

Usar plantillas estándar
Definir guía de estilo (naming, formatos)
Todos usan el mismo lenguaje para los mismos conceptos
Mismo formato para ejemplos

Ejemplo de inconsistencia:

En un documento dicen "Usuario"
En otro dicen "Perfil de usuario"
En otro dicen "Cuenta"
→ Confusión: ¿son lo mismo?

Ejemplo consistente:

Establecer: "Usuario" = Persona registrada
"Usuario activo" = Usuario que ha iniciado sesión
"Perfil de usuario" = Página con datos del usuario

Todos los documentos usan estos términos igual.

3.4 Actualización Regular¶

¿Qué significa?: Mantener la documentación sincronizada con el código

Cómo lograrlo:

Actualizar documentación cuando haces cambios
Revisar documentación regularmente
Incluir "fecha de última actualización"
Control de versiones para documentación

Ejemplo de problema:

Documentación dice: "Máximo 100 usuarios por proyecto"
Código en versión 2.5 permite 1000
→ Documentación obsoleta causa confusión

3.5 Accesibilidad¶

¿Qué significa?: Documentación fácil de encontrar y acceder

Cómo lograrlo: s - Disponible en línea (accesible desde navegador) - Disponible en dispositivos móviles - Sistema de navegación intuitivo - Búsqueda robusta - Múltiples formatos (web, PDF, etc.)

Estructura de accesibilidad:

DOCUMENTACIÓN
├─ Para usuarios
│  ├─ Guía rápida de inicio
│  ├─ Manual completo
│  ├─ FAQs
│  └─ Vídeos tutoriales
├─ Para desarrolladores
│  ├─ Arquitectura
│  ├─ Guía de instalación
│  ├─ API Reference (Javadoc)
│  └─ Guía de contribución
└─ Para administradores
   ├─ Instalación
   ├─ Configuración
   ├─ Respaldo y recuperación
   └─ Troubleshooting

4. Documentación como Requisito de Calidad¶

La documentación es parte de la calidad del software:

Con documentación completa:

Nuevos desarrolladores entienden código rápido
Cambios son más seguros
Menos dependencia de personas
Usuarios entienden cómo usar
Fácil de mantener y escalar

Sin documentación:

Código inexplicable
Cambios rompen cosas
Solo una persona sabe
Usuarios no saben qué hacer
Deuda técnica crece

Actividades¶

AC907. Elige una aplicación que usas regularmente (Spotify, Gmail, Whatsapp, etc.).

Tu tarea: Escribe un manual de usuario para una funcionalidad específica dirigido a usuarios sin experiencia técnica.

Incluye:
1. Introducción: Qué es la funcionalidad
2. Requisitos previos: Qué necesitas antes
3. Pasos paso a paso: Números, claros, simples
4. Capturas de pantalla o descripciones visuales
5. Problemas comunes: Qué puede salir mal y cómo arreglarlo
6. Preguntas frecuentes: 3-5 FAQs
Requisitos:
- Máximo 2 páginas
- Lenguaje simple (sin jerga técnica)
- Una persona sin experiencia debe entenderlo sin problemas
- Incluir ejemplos concretos
Nota: Escrito por ti, no por IA. Demuestra que entiendes la funcionalidad.
AC908. Coge un proyecto/código que hayas escrito (de cualquier asignatura).

Tu tarea: Añade documentación de calidad:
1. Javadoc: Documenta 5 métodos importantes con:
- Descripción clara de qué hace
- @param para cada parámetro
- @return explicando qué devuelve
- @throws si lanza excepciones
1. Comentarios: Añade comentarios explicando el "por qué" en partes complejas
2. README.md: Crea un README que incluya:
- Descripción del proyecto
- Requisitos para ejecutar
- Cómo instalar/ejecutar
- Estructura del proyecto
- Ejemplos de uso
1. Especificación de diseño: Documenta: - Arquitectura general (diagrama si es posible) - Decisiones de diseño importantes - Patrones usados
Entrega: Código documentado + archivos de documentación (README, especificación)

Criterios de evaluación:
- ¿Es clara la documentación?
- ¿Es concisa (sin información innecesaria)?
- ¿Es consistente (mismo estilo)?
- ¿Es accesible (fácil de leer)?
- ¿Permite a otros entender tu código?