1. Documentación y Diagramas

Lenguajes, herramientas y tipos de diagramas para documentar sistemas de software efectivamente.

1.1 📝 Documentación de Software

Qué: Información escrita o visual que explica cómo funciona, se usa o se mantiene un sistema.

Por qué: Código se lee 10x más de lo que se escribe. Buena doc = onboarding rápido, menos bugs, mejor mantenimiento.

Quién: Developers, technical writers, architects.

Cuándo: Continuo, como parte del desarrollo (no después).

Esfuerzo: 15% del tiempo de desarrollo, paga dividendos en mantenimiento.

1.2 📖 Lenguajes de Documentación

1.3 🎨 Herramientas de Diagramas

1.3.1 Diagramas como Código

Ventajas diagrams-as-code:

• ✅ Versionado en Git
• ✅ Diffs legibles
• ✅ CI/CD automation
• ✅ No desincroniza con código

1.3.2 Herramientas Visuales

1.4 📊 Tipos de Diagramas

1.4.1 Diagrama de Flujo (Flowchart)

Qué: Representa proceso con pasos y decisiones.

Cuándo: Algoritmos, procesos de negocio, workflows.

Mermaid:

graph TD
    A[Start] --> B{Usuario autenticado?}
    B -->|Sí| C[Mostrar dashboard]
    B -->|No| D[Redirigir a login]
    C --> E[End]
    D --> E

Símbolos:

• Óvalo: Inicio/Fin
• Rectángulo: Proceso
• Rombo: Decisión
• Paralelogramo: Input/Output

1.4.2 C4 Model (Context, Containers, Components, Code)

Qué: Niveles de abstracción para arquitectura de software.

Por qué: Comunicar arquitectura a diferentes audiencias.

Niveles:

Ejemplo C2 (Mermaid):

C4Container
    Person(user, "Usuario", "Cliente de e-commerce")
    Container_Boundary(system, "Sistema E-commerce") {
        Container(web, "Web App", "React", "SPA")
        Container(api, "API", "FastAPI", "REST API")
        Container(db, "Database", "PostgreSQL", "Datos")
    }
    System_Ext(payment, "Payment Gateway", "Stripe")

    Rel(user, web, "Usa", "HTTPS")
    Rel(web, api, "Llama", "JSON/HTTPS")
    Rel(api, db, "Lee/Escribe", "SQL")
    Rel(api, payment, "Procesa pagos", "HTTPS")

Herramientas: Structurizr, C4-PlantUML

1.4.3 Diagrama Entidad-Relación (ER)

Qué: Modela entidades, atributos y relaciones de base de datos.

Cuándo: Diseñar schema de BD, documentar modelo de datos.

Mermaid:

erDiagram
    USER || -- o{ ORDER : places
    USER {
        int id PK
        string email
        string name
    }
    ORDER || -- |{ ORDER_ITEM : contains
    ORDER {
        int id PK
        int user_id FK
        datetime created_at
        string status
    }
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }
    PRODUCT || -- o{ ORDER_ITEM : "ordered in"
    PRODUCT {
        int id PK
        string name
        decimal price
    }

Cardinalidad:

• || -- ||: One-to-one
• || -- o{: One-to-many
• }o--o{: Many-to-many

1.4.4 Diagrama de Clases (UML)

Qué: Muestra clases, atributos, métodos y relaciones OOP.

Cuándo: Diseñar arquitectura OOP, refactoring.

PlantUML:

Relaciones:

• -->: Asociación
• *--: Composición
• o--: Agregación
• <| --: Herencia
• <..: Dependencia

1.4.5 Diagrama de Secuencia

Qué: Muestra interacciones entre objetos en el tiempo.

Cuándo: Documentar flujos complejos, API calls, async operations.

Mermaid:

sequenceDiagram
    participant U as Usuario
    participant W as Web App
    participant A as API
    participant D as Database
    participant P as Payment Gateway

    U->>W: Click "Comprar"
    W->>A: POST /orders
    A->>D: INSERT order
    D-->>A: order_id
    A->>P: POST /charge
    P-->>A: success
    A->>D: UPDATE order status
    A-->>W: 201 Created
    W-->>U: Confirmación

Símbolos:

• ->: Llamada síncrona
• -->: Respuesta
• ->>: Llamada asíncrona
• -->>: Respuesta asíncrona

1.4.6 Diagrama de Componentes

Qué: Muestra organización y dependencias entre componentes del sistema.

Cuándo: Arquitectura modular, microservicios.

PlantUML:

1.4.7 Diagrama de Estados (State Machine)

Qué: Muestra estados posibles de un objeto y transiciones.

Cuándo: Workflows, FSM, ciclos de vida.

Mermaid:

stateDiagram-v2
    [*] --> Draft
    Draft --> Review: submit()
    Review --> Approved: approve()
    Review --> Rejected: reject()
    Approved --> Published: publish()
    Rejected --> Draft: revise()
    Published --> Archived: archive()
    Archived --> [*]

1.4.8 Diagrama de Arquitectura (System Design)

Qué: Vista de alto nivel de arquitectura del sistema.

Cuándo: Onboarding, design reviews, documentación.

Ejemplo (texto Mermaid):

graph TB
    subgraph "Client Layer"
        Web[Web App<br/>React]
        Mobile[Mobile App<br/>React Native]
    end

    subgraph "API Layer"
        Gateway[API Gateway<br/>Kong]
        Auth[Auth Service]
        Users[Users Service]
        Orders[Orders Service]
    end

    subgraph "Data Layer"
        PG[(PostgreSQL)]
        Redis[(Redis)]
        S3[(S3)]
    end

    Web --> Gateway
    Mobile --> Gateway
    Gateway --> Auth
    Gateway --> Users
    Gateway --> Orders
    Auth --> Redis
    Users --> PG
    Orders --> PG
    Orders --> S3

1.4.9 Diagrama de Despliegue

Qué: Muestra infraestructura física/lógica donde corre el sistema.

Cuándo: DevOps, infraestructura, deployment planning.

PlantUML:

1.5 📚 Tipos de Documentación

1.6 ✍️ Best Practices Documentación

1.7 🚫 Anti-patrones

1.8 📚 Recursos

• Mermaid Live Editor
• PlantUML Documentation
• C4 Model
• Write the Docs
• Diátaxis Framework - Docs structure