Como documentar un proyecto de software correctamente

Escribir codigo es solo la mitad del trabajo. La otra mitad es documentarlo. En universidades como UNAH, UNITEC, UTH y CEUTEC, los proyectos de ingenieria en sistemas pierden puntos no por fallos tecnicos, sino por documentacion incompleta o desorganizada. Aqui te explicamos como hacerlo bien.

Por que documentar importa

Un proyecto sin documentacion es un proyecto que nadie puede mantener, evaluar ni replicar. Tu asesor de tesis necesita entender que hace tu sistema sin ejecutar el codigo. Tu jurado necesita verificar que cumpliste los requerimientos. Y tu mismo, seis meses despues, necesitas recordar por que tomaste ciertas decisiones.

La documentacion tecnica no es un extra. Es un entregable obligatorio.

Los 4 documentos esenciales

1. README del proyecto

Es lo primero que cualquier persona lee al abrir tu repositorio. Debe responder tres preguntas: que es, como se instala y como se ejecuta.

Estructura minima:

• Nombre del proyecto — Titulo claro y descriptivo
• Descripcion — Que problema resuelve, en una o dos oraciones
• Requisitos previos — Versiones de lenguaje, base de datos, dependencias
• Instalacion — Pasos exactos para levantar el proyecto desde cero
• Uso — Comandos principales o capturas de pantalla
• Tecnologias utilizadas — Stack completo con versiones
• Autores — Nombres y roles del equipo

Ejemplo practico:

Si tu proyecto es un sistema de gestion de expedientes para una clinica, tu README deberia incluir: "Sistema web desarrollado con React y Node.js para digitalizar expedientes clinicos. Permite registro de pacientes, historial de consultas y generacion de reportes PDF."

2. Manual de usuario

Va dirigido a la persona que usara el sistema sin conocimientos tecnicos. Debe ser visual, con capturas de pantalla de cada pantalla y flujo.

Que incluir:

• Requisitos del sistema (navegador, resolucion)
• Acceso al sistema (URL, credenciales de prueba)
• Descripcion de cada modulo con capturas
• Paso a paso de las funciones principales
• Preguntas frecuentes y solucion de errores comunes

Evita el lenguaje tecnico. Si tu usuario es una recepcionista de clinica, no le digas "hacer un POST al endpoint". Dile "presione el boton Guardar".

3. Manual tecnico (o del sistema)

Va dirigido a desarrolladores que necesiten mantener, modificar o escalar tu sistema. Es el documento mas extenso y detallado.

Secciones clave:

• Arquitectura del sistema — Diagrama general de componentes
• Modelo de datos — Diagrama entidad-relacion con descripcion de cada tabla
• Diccionario de datos — Nombre, tipo, restricciones y descripcion de cada campo
• APIs/Endpoints — Ruta, metodo HTTP, parametros, respuestas esperadas
• Configuracion del entorno — Variables de entorno, puertos, servicios externos
• Estructura de carpetas — Arbol del proyecto con descripcion de cada directorio
• Dependencias — Lista completa con versiones y proposito de cada una
• Procedimientos de despliegue — Como pasar de desarrollo a produccion

4. Diagramas UML

Los diagramas UML son el lenguaje universal de la ingenieria de software. Tu asesor espera verlos y tu jurado los va a evaluar.

Diagramas obligatorios segun el tipo de proyecto:

Diagrama	Cuando usarlo	Que muestra
Casos de uso	Siempre	Actores y funcionalidades del sistema
Clases	Proyectos con POO	Estructura de clases y relaciones
Secuencia	Flujos complejos	Interaccion entre componentes en el tiempo
Entidad-relacion	Proyectos con BD	Tablas, campos y relaciones
Actividades	Procesos de negocio	Flujo paso a paso de un proceso
Despliegue	Sistemas distribuidos	Infraestructura y servidores

Herramientas recomendadas:

• draw.io (diagrams.net) — Gratuita, funciona en navegador, exporta a PNG y PDF
• Lucidchart — Version gratuita para estudiantes con correo .edu
• PlantUML — Para generar diagramas desde texto (ideal si usas Markdown)
• StarUML — Completa para diagramas UML profesionales

Errores que bajan nota

1. Documentar al final — La documentacion se escribe durante el desarrollo, no la noche antes de la entrega
2. Capturas desactualizadas — Si cambiaste la interfaz, actualiza las capturas
3. Copiar documentacion de otros proyectos — Los asesores lo notan inmediatamente
4. Diagramas inconsistentes — Si tu diagrama de clases no coincide con tu codigo, pierdes credibilidad
5. Falta de diccionario de datos — Es uno de los entregables mas solicitados y mas olvidados
6. README vacio — Entregar un repositorio sin README es como entregar un informe sin portada

Plantilla de estructura de documentacion

Para que tu entrega quede profesional, organiza tus documentos asi:

/documentacion
  /manual-usuario
    manual-usuario.pdf
    /capturas
  /manual-tecnico
    manual-tecnico.pdf
    diccionario-datos.pdf
    /diagramas
      casos-de-uso.png
      diagrama-clases.png
      diagrama-er.png
      diagrama-secuencia.png
  README.md

Consejos finales

Usa un lenguaje consistente. Si llamas "paciente" a un actor en el diagrama de casos de uso, no lo llames "cliente" en el manual de usuario.

Versiona tu documentacion. Si tu sistema cambia, tu documentacion cambia. Incluye un numero de version y fecha de ultima actualizacion.

Pide retroalimentacion. Dale tu manual de usuario a alguien que no sea de sistemas. Si no lo entiende, reescribelo.

En Folium Labs desarrollamos software y documentacion tecnica profesional. Si necesitas que tu proyecto tenga manuales, diagramas UML y documentacion que cumpla los estandares de tu universidad, podemos ayudarte.

---

La documentacion es la diferencia entre un proyecto aprobado y un proyecto destacado. Invierte el tiempo necesario y tu jurado lo reconocera.

Cotiza tu proyecto de software →