DEV Community: Matias Rojas

¿Cómo documentar sistemas empresariales?

Matias Rojas — Sat, 06 Dec 2025 19:19:55 +0000

Introducción

En el mundo real, muy pocos desarrolladores documentan sus sistemas con el mismo nivel de importancia que el código.

Y sin documentación, un sistema empresarial no es un producto completo, sino apenas un conjunto de funciones que solo entiende quien lo construyó.

La documentación no es un extra: es parte del sistema.

Ayuda a escalar equipos, simplifica auditorías, reduce la rotación costosa y preserva el conocimiento crítico del negocio.

En este artículo vas a ver cómo documentar un sistema empresarial de manera profesional, qué tipos de documentación son obligatorios y cómo integrarlos en la operación diaria.

1. Documentación funcional

La documentación funcional explica qué hace el sistema, por qué lo hace y cómo debería comportarse desde el punto de vista del negocio.

Es la documentación que podrían leer:

Product owners
Stakeholders
Analistas de negocio
Nuevos desarrolladores
QA / testers

¿Qué debe incluir?

Objetivo del sistema: qué problema resuelve y para quién
Actores: usuarios, roles, permisos
Casos de uso: qué debe poder hacer cada tipo de usuario
Reglas de negocio: descuentos, validaciones, autorizaciones, cálculos
Escenarios excepcionales: qué ocurre cuando algo falla (stock insuficiente, pago rechazado, datos incompletos)

Esta documentación debe responder preguntas como:

✔ ¿Cómo funciona?
✔ ¿Qué pasa cuando ocurre X?
✔ ¿Por qué esta regla existe así?

2. Documentación técnica

La documentación técnica explica cómo está construido el sistema, qué decisiones arquitectónicas se tomaron y cómo funciona internamente.

Está dirigida a desarrolladores, DevOps y arquitectos.

¿Qué debe incluir?

Arquitectura general

Monolito, microservicios, colas, workers, integraciones externas, cron jobs.
Diagrama de componentes

Cómo se conectan los módulos internos.
Dependencias críticas

APIs externas, servicios de terceros, librerías esenciales.
Flujos técnicos relevantes

Procesamiento de pagos, sincronización de inventario, generación de reportes, etc.
Infraestructura

Ambientes productivo y staging, CI/CD, backups, escalabilidad.
Políticas técnicas

Versionado, seguridad, encriptación, manejo de errores.

3. Diccionario de datos

El diccionario de datos describe las entidades del sistema, sus campos y la lógica asociada.

Es indispensable en sistemas empresariales, especialmente contables, logísticos y financieros.

¿Qué debe incluir para cada tabla o modelo?

Nombre de la entidad
Propósito
Campos: nombre, tipo, descripción
Reglas asociadas: únicos, constraints, validaciones
Relación con otras entidades
Impacto en la lógica del negocio

Un buen diccionario de datos permite:

✔ Evitar campos huérfanos o duplicados
✔ Mantener integridad en los reportes
✔ Asegurar que todos entienden la misma semántica

Por ejemplo, el campo importe_total puede significar cosas distintas si no se define:

subtotal, total con impuestos, total sin descuentos, etc.

4. Flujos de estados

Los sistemas maduros definen estados y transiciones claras: pedidos, pagos, usuarios, tickets, envíos, facturas, etc.

Documentar los flujos de estado permite entender:

Qué estados existen
Qué reglas permiten pasar de un estado a otro
Qué estados son finales
Qué estados dependen de validaciones externas
Qué procesos automáticos intervienen

Sin un flujo documentado, cada área del negocio interpreta el estado a su manera, lo que genera inconsistencias, reclamos y caos operativo.

5. Manuales para usuarios internos

Esto incluye:

Soporte
Atención al cliente
Finanzas
Logística
Administración
Supervisores

Los manuales internos deben explicar:

Pasos para cada acción frecuente
Errores comunes y cómo resolverlos
Permisos según rol
Procedimientos del día a día
Ejemplos visuales y capturas de pantalla
Mejores prácticas operativas

6. Scripts de auditoría

Los scripts de auditoría permiten:

Volver a calcular montos
Validar integridad
Detectar inconsistencias
Comparar estados actuales vs históricos
Reconstruir operaciones críticas

Tipos típicos de auditoría:

Ventas vs facturación
Stock teórico vs stock real
Integridad de registros: órdenes sin pago, pagos sin orden
Repetición de cálculos históricos
Logs de acciones críticas

Estos scripts deben estar documentados, versionados y probados.

Conclusión

Un sistema empresarial bien documentado:

✔ Reduce el soporte
✔ Evita errores caros
✔ Alinea al negocio
✔ Facilita auditorías
✔ Acelera onboarding
✔ Aumenta la calidad del software

La documentación es un componente más del sistema.

Gracias por leer 🙌

Modernizá tu Django Admin con Unfold (sin tocar una línea de CSS)

Matias Rojas — Mon, 31 Mar 2025 01:41:17 +0000

¿Qué es Unfold?

Unfold es una interfaz moderna para el Django Admin, construida con Tailwind CSS.

Está diseñada para ofrecer una experiencia visual más atractiva y una mejor usabilidad, sin necesidad de escribir código frontend.

Lo mejor de todo: no tenés que cambiar la lógica de tus modelos, ni usar React, ni crear templates personalizados.

Solo con unas pocas configuraciones, ya podés transformar el aspecto de tu panel administrativo.

🔧 ¿Qué ofrece Unfold?

Dashboard con métricas y paneles personalizables
Diseño responsive por defecto
Personalización visual desde Python, sin tocar HTML o CSS

Es una solución ideal para quienes trabajamos desde el backend, pero queremos entregar un producto final más pulido y profesional.

📌 Podés ver la demo oficial en:

👉 Demo

Diferencias entre el Admin clásico y Unfold

Django viene con un panel administrativo muy funcional, pero con una estética básica y pocas herramientas visuales listas para usar.

Unfold no reemplaza el admin clásico, sino que lo mejora desde adentro, aplicando un diseño moderno y nuevas formas de presentar los datos.

Diferencias Clave

Característica	Django Admin clásico	Django Admin con Unfold
Estética	Simple, minimalista	Moderna, basada en Tailwind CSS
Layout	Vertical, lineal	Responsive, adaptable
Personalización visual	Requiere CSS/JS	Desde Python, sin CSS
Dashboard	Estático, sin métricas	Paneles con métricas y widgets
Responsive	Limitado	Totalmente adaptable
Integración con `ModelAdmin`	Total	Total (hereda de ModelAdmin)
Requiere cambiar tu flujo de trabajo	No	No

🔍 En resumen: Unfold respeta todo lo bueno del admin clásico, pero te da herramientas visuales listas para usar con solo un par de configuraciones.

Este cambio es ideal tanto para proyectos personales como para paneles internos de clientes o equipos de trabajo, donde la presentación también importa.

Instalación

Ejecute el siguiente comando en su entorno virtual para instalar Unfold:

pip install django-unfold

Después de una instalación exitosa, agregue Unfold a INSTALLED_APPS en el archivo Django settings.py.

INSTALLED_APPS = [
    "unfold",  # Debe ir antes que django.contrib.admin
    "unfold.contrib.filters",          # Opcional: filtros personalizados
    "unfold.contrib.forms",            # Opcional: mejoras en formularios
    "unfold.contrib.inlines",          # Opcional: mejoras en inlines
    "unfold.contrib.import_export",    # Opcional: si usás django-import-export
    "unfold.contrib.guardian",         # Opcional: si usás django-guardian
    "unfold.contrib.simple_history",   # Opcional: si usás django-simple-history
    "django.contrib.admin",            # Requerido
    ...
]

📌 Podés ver todas las opciones de configuración en:

👉 Documentación

La próxima vez que visites tu panel de administración, serás recibido con una interfaz moderna, limpia y responsive.

Personalización de un modelo

Este es el único paso importante que sí cambia respecto al admin clásico:
Las clases admin deben heredar de unfold.admin.ModelAdmin, no del django.contrib.admin.ModelAdmin.

Ejemplo Django Clásico:

from django.contrib import admin
from .models import Autor

@admin.register(Autor)
class AutorAdmin(admin.ModelAdmin):
    list_display = ("nombre", "nacionalidad")
    search_fields = ("nombre", "nacionalidad")

Ejemplo Unfold:

from django.contrib import admin
from unfold.admin import ModelAdmin
from .models import Autor

@admin.register(Autor)
class AutorAdmin(ModelAdmin):
    list_display = ("nombre", "nacionalidad")
    search_fields = ("nombre", "nacionalidad")

Funciones destacadas

No es necesario modificar ajustes adicionales, pero se puede lograr mucho haciendolo. Dado que unfold sobrescribe algunos comportamientos predeterminados, los desarrolladores lograron añadir funcionalidades adicionales al panel de administración de Django. A continuación, destacaré mis dos favoritas: la barra lateral personalizada y el dashboard.

Barra Lateral

Unfold te permite estructurar la navegación de la barra lateral a tu gusto. Por defecto, se ven los modelos registrados uno abajo de otro. Esto puede funcionar bien al principio, pero se vuelve difícil de manejar a medida que se agregan más modelos. Una buena forma de evitarlo es añadir una capa de navegación adicional: las aplicaciones donde residen los modelos.

En el archivo conifg/settings.py, agregue lo siguiente:

from django.urls import reverse_lazy
from django.utils.translation import gettext_lazy as _

UNFOLD = {
    "SITE_HEADER": "Admin Libros",

    "SIDEBAR": {
        "show_search": True,
        "show_all_applications": False,
        "navigation": [
            {
                "title": _("Gestión de Libros"),
                "separator": False,
                "collapsible": True,
                "items": [
                    {
                        "title": _("Autores"),
                        "icon": "person",
                        "link": reverse_lazy("admin:books_autor_changelist"),
                    },
                    {
                        "title": _("Libros"),
                        "icon": "menu_book",
                        "link": reverse_lazy("admin:books_libro_changelist"),
                    },
                ],
            },
        ],
    },
}

Esto creará un elemento de navegación plegable, con los modelos registrados. Cada modelo también tiene su propio icono, obtenido de Google Fonts. Verás una barra lateral mucho más ordenada y profesional:

Dashboard

La característica principal de Unfold es que te permite desarrollar paneles personalizados de forma eficiente. Estos paneles son útiles para supervisar la actividad de tu aplicación, lo que te permite ver lo que sucede en cualquier momento.

Recomiendo configurar el panel de control como página de inicio del panel de administración, para poder verlo cada vez que se inicia sesión. Para configurarlo, debemos seguir los siguientes pasos:

actualice el archivo config/settings.py para incluir lo siguiente:

"DASHBOARD_CALLBACK": "config.admin.dashboard_callback",

Registramos el dashboard en la barra lateral:

"SIDEBAR": {
    "show_search": True,  
    "show_all_applications": False,  
    "navigation": [
            {
                "title": _("Menú Principal"),
                "separator": True,
                "collapsible": True,
                "items": [
                    {
                        "title": _("Dashboard"),
                        "icon": "dashboard",
                        "link": reverse_lazy("admin:index"),
                    },
                ],
            },
}

Ya que estamos en settings.py también vemos las plantillas:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR / "config/templates"],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

Luego, creamos el archivo config/admin.py y completamos con lo siguiente:

from books.models import Autor, Libro

def dashboard_callback(request, context):
    """
    Dashboard personalizado para Unfold.
    """
    total_autores = Autor.objects.count()
    total_libros = Libro.objects.count()

    context.update({
        "kpis": [
            {
                "title": "Total de Autores",
                "metric": total_autores,
            },
            {
                "title": "Total de Libros",
                "metric": total_libros,
            },
        ],
    })
    return context

Y por último creamos una plantilla que lo renderice, en config/templates/admin/index.html

{% extends "admin/base.html" %}
{% load unfold %}

{% block content %}
  {% component "unfold/components/container.html" %}
    <div class="grid grid-cols-2 gap-4">
      {% for metric in kpis %}
        {% component "unfold/components/card.html" %}
          {% component "unfold/components/text.html" %}
            {{ metric.title }}
          {% endcomponent %}
          {% component "unfold/components/title.html" %}
            {{ metric.metric }}
          {% endcomponent %}
        {% endcomponent %}
      {% endfor %}
    </div>
  {% endcomponent %}
{% endblock %}

¡Listo! 🎉

Al ejecutar el servidor y acceder a /admin, se mostrará el siguiente panel de control.

Espero que esto te proporcione una idea para desarrollar tus propios dashboards dentro del panel de administración de Django con Unfold. Implementamos algunas funciones útiles, ¡pero no todas! Asegúrate de consultar la documentación de Unfold para explorar todas las opciones disponibles.

A continuación les dejo el código completo de esta guía, se encuentra en este repositorio.

Conclusión

Unfold te permite modernizar el Django Admin con muy poco esfuerzo y sin escribir una sola línea de CSS.

Es simple, potente y perfecto para quienes trabajamos del lado del backend.

Probalo, personalizalo y llevá tu panel al siguiente nivel.

Gracias por leer 🙌