En este primer módulo vamos a sentar las bases del curso. Antes de aprender a hacer README, manuales, esquemas o documentación profesional, es importante entender qué es realmente la documentación técnica, por qué es tan importante y por qué en tantos proyectos termina siendo un desastre o directamente no existe.
La idea de esta unidad es que el alumno comprenda que documentar no es “rellenar papel”, sino una parte fundamental del trabajo técnico. Un proyecto mal documentado puede convertirse en un problema incluso aunque técnicamente esté bien hecho.
En este módulo se trabajará:
- qué es la documentación técnica
- por qué suele fallar la documentación en proyectos reales
- diferencias entre documentar para uno mismo, para un equipo y para un cliente
- tipos de documentación en informática
¿Qué es la documentación técnica?
La documentación técnica es el conjunto de textos, esquemas, instrucciones, referencias y evidencias que explican cómo funciona un sistema, cómo se instala, cómo se usa, cómo se mantiene o cómo se ha construido.
Dicho de forma sencilla:
la documentación técnica sirve para que una persona pueda entender, usar, mantener, revisar o continuar un trabajo técnico sin depender totalmente de quien lo creó.
Ejemplos de documentación técnica
En informática, documentación técnica puede ser por ejemplo:
- un README de un proyecto en GitHub
- un manual de instalación de un servidor
- una guía de despliegue de una aplicación
- un documento con la arquitectura de una red
- un procedimiento para hacer copias de seguridad
- una memoria técnica de un proyecto
- un informe de auditoría o de incidencia
- una wiki interna con procesos y configuraciones
¿Por qué es tan importante documentar?
Porque en el mundo real los proyectos no viven solo el día que se crean.
Un proyecto técnico normalmente pasa por varias fases:
- se diseña
- se implementa
- se prueba
- se entrega
- se mantiene
- se modifica
- se corrige
- se reutiliza o amplía
Si no existe documentación, todo depende de la memoria de una persona.
Y eso provoca errores, pérdida de tiempo, dependencia del autor original y muchos problemas cuando hay que revisar o retomar el trabajo.
Una idea clave
Un proyecto sin documentación puede funcionar hoy, pero convertirse en un problema mañana.
¿Qué suele pasar en los proyectos reales?
En muchísimos proyectos la documentación falla por motivos muy parecidos.
Problemas habituales
- no se documenta desde el principio
- se deja “para el final”
- se escribe deprisa y sin estructura
- se da por hecho que cosas importantes “ya se entienden”
- se documenta pensando solo en quien lo ha hecho
- la documentación se queda desactualizada
- no se distingue entre tipos de documento
- se mezcla información técnica, organizativa y personal sin orden
- no se incluyen evidencias, validaciones ni contexto
Resultado de todo esto
Al final aparecen documentos que:
- no sirven para instalar nada
- no explican bien el proyecto
- no ayudan a otra persona
- no permiten reproducir el trabajo
- quedan abandonados
- generan confusión en lugar de ayudar
Documentar no es escribir mucho
Uno de los errores más frecuentes es pensar que “más texto” significa “mejor documentación”.
No siempre es así.
Una buena documentación no tiene por qué ser enorme.
Tiene que ser:
- clara
- ordenada
- útil
- precisa
- fácil de consultar
- pensada para quien la va a leer
Hay documentación breve que funciona muy bien, y documentación larguísima que no sirve para nada.
¿Para quién se documenta?
Esta es una de las preguntas más importantes del módulo.
No se documenta igual para todos los destinatarios.
La forma de documentar cambia mucho según quién va a leer el documento.
Documentar para uno mismo
Cuando una persona documenta para sí misma, normalmente busca:
- recordar pasos
- guardar comandos
- anotar configuraciones
- dejar registro de errores y soluciones
- construir una base de conocimiento personal
Características habituales
- más libertad en el formato
- lenguaje más directo
- menos contexto general
- más valor práctico inmediato
- organización pensada para el propio autor
Ejemplo
Una nota en Obsidian con comandos para configurar Apache y MySQL en Ubuntu.
Documentar para un equipo
Cuando se documenta para un equipo, la documentación debe ser más clara, más ordenada y más estandarizada.
Aquí ya no basta con que “yo lo entienda”.
Tiene que entenderlo otra persona que quizá no estuvo presente durante el proceso.
Características habituales
- lenguaje más claro y neutral
- estructura estable
- pasos reproducibles
- mayor precisión
- contexto suficiente
- convenciones compartidas
- mantenimiento continuo
Ejemplo
Una guía interna para desplegar una aplicación web en un servidor de pruebas.
Documentar para un cliente o para una entrega formal
Aquí la documentación debe tener además una presentación más cuidada y una explicación más completa del contexto, objetivos y resultados.
Características habituales
- tono más profesional
- mejor presentación visual
- organización muy clara
- explicación de objetivos, alcance y resultados
- vocabulario comprensible para perfiles no tan técnicos
- formato más formal: Word, PDF, memoria, informe, etc.
Ejemplo
La memoria técnica de un proyecto final, con portada, índice, imágenes, fases, decisiones técnicas y conclusiones.
Comparativa rápida
| Tipo de documentación | Destinatario | Objetivo principal | Estilo habitual |
|---|---|---|---|
| Personal | Uno mismo | Recordar y reutilizar | Directo y práctico |
| De equipo | Compañeros o técnicos | Compartir conocimiento y mantener procesos | Claro, estructurado y reproducible |
| Formal o de cliente | Profesorado, cliente, responsables, tribunal | Explicar, justificar y entregar | Profesional, completo y bien presentado |
Tipos de documentación en informática
En informática no existe un solo tipo de documentación.
Hay varias categorías, y cada una cumple una función diferente.
Entender esto es muy importante porque muchos errores vienen de mezclarlo todo en un solo documento.
1. Documentación de producto
Es la documentación que explica un producto, una aplicación, un sistema o una herramienta concreta.
Suele incluir
- qué es
- para qué sirve
- cómo se instala
- cómo se configura
- cómo se usa
- qué requisitos tiene
- qué estructura interna presenta
Ejemplos
- README de una aplicación
- manual de usuario técnico
- documentación de API
- guía de instalación de software
2. Documentación de proceso
Explica cómo se realiza una tarea o un conjunto de tareas.
No se centra tanto en “qué es el producto”, sino en qué pasos hay que seguir para hacer algo correctamente.
Suele incluir
- objetivo del proceso
- requisitos previos
- secuencia de pasos
- validación
- problemas frecuentes
- resultado esperado
Ejemplos
- procedimiento de despliegue
- guía de copia de seguridad
- proceso de alta de usuarios
- checklist de hardening
- guía de restauración de servicios
3. Documentación operativa
Es la documentación que sirve para operar, administrar o mantener sistemas en funcionamiento.
Está muy relacionada con ASIR, sistemas, administración, redes y explotación técnica.
Suele incluir
- configuraciones
- servicios
- puertos
- rutas
- comandos
- validaciones
- acciones de mantenimiento
- actuación ante fallos
Ejemplos
- runbook de administración
- guía de reinicio de servicios
- procedimientos de monitorización
- documentación de una infraestructura de red
- inventario técnico de máquinas o servicios
4. Documentación de soporte
Es la documentación pensada para resolver dudas, incidencias o problemas recurrentes.
Suele incluir
- preguntas frecuentes
- errores comunes
- pasos de comprobación
- diagnósticos básicos
- soluciones conocidas
Ejemplos
- FAQ técnica
- base de conocimiento
- guía de resolución de incidencias
- documentación de errores frecuentes
5. Documentación académica y de entrega
Es muy habitual en entornos educativos, proyectos fin de ciclo, memorias, prácticas guiadas y entregas técnicas.
Aquí no solo importa el funcionamiento, sino también explicar el proceso, justificar decisiones y demostrar el trabajo realizado.
Suele incluir
- introducción
- objetivos
- análisis
- requisitos
- diseño
- implementación
- capturas
- pruebas
- conclusiones
- bibliografía o referencias
Ejemplos
- memoria de TFG o TFM
- entrega de una práctica técnica
- informe de laboratorio
- documentación de un proyecto de clase
6. Documentación viva vs. documentación abandonada
Este punto es especialmente importante.
Documentación viva
Es la que se mantiene actualizada y sigue siendo útil con el paso del tiempo.
Características
- se revisa
- se corrige
- se adapta a cambios
- refleja el estado real del proyecto
- acompaña al trabajo técnico
Documentación abandonada
Es la que se escribió una vez y nunca más se revisó.
Problemas típicos
- comandos que ya no sirven
- capturas antiguas
- rutas que han cambiado
- versiones desactualizadas
- información incompleta o engañosa
Idea importante
Una documentación antigua puede ser peor que no tener documentación, porque da una falsa sensación de confianza.
Ejemplo sencillo para entenderlo
Imagina una práctica donde un alumno monta un servidor web con Apache, PHP y MySQL.
Si documenta bien:
- explica requisitos
- indica comandos
- organiza pasos
- muestra validaciones
- añade errores encontrados
- incluye estructura del proyecto
- deja claro cómo reproducirlo
Si documenta mal:
- pone cuatro comandos sueltos
- no indica orden
- no explica qué instaló realmente
- no muestra resultado
- no aclara versiones ni rutas
- no se entiende qué hizo ni cómo repetirlo
Técnicamente puede haber hecho lo mismo, pero el valor del trabajo cambia muchísimo.
Errores muy frecuentes al empezar a documentar
Estos errores conviene enseñarlos desde el principio:
- escribir pensando “ya me acordaré”
- no poner títulos claros
- mezclar teoría y práctica sin orden
- usar frases ambiguas
- copiar comandos sin explicar para qué sirven
- no validar resultados
- no anotar problemas reales
- no diferenciar entre borrador y versión final
- documentar solo el resultado y no el proceso
Ejemplos
| Caso | Tipo de documentación | Destinatario | Observación |
|---|---|---|---|
| README de instalación | Documentación de producto | Usuario técnico o desarrollador | Explica qué es y cómo usarlo |
| Documento en Word con memoria | Documentación académica y de entrega | Profesorado, cliente o tribunal | Presentación formal |
| Nota de Obsidian con comandos | Documentación personal u operativa | Uno mismo | Uso interno y práctico |
| Guía de despliegue en Apache | Documentación de proceso u operativa | Equipo técnico | Procedimiento reproducible |
| Lista de errores frecuentes | Documentación de soporte | Usuarios o técnicos | Ayuda a resolver incidencias |
| Documento obsoleto | Documentación abandonada | Puede confundir a cualquiera | No refleja la realidad actual |
Ideas clave para recordar
Documentar no es decorar un proyecto: es hacerlo comprensible y mantenible.
Una buena documentación ayuda a repetir, mantener, explicar y mejorar un trabajo técnico.
No toda la documentación sirve para lo mismo: hay que elegir bien el tipo de documento.
La documentación útil está pensada para quien la va a leer.
Una documentación sin mantenimiento termina perdiendo valor.
Caso de uso: despliegue de una aplicación web interna para gestión de incidencias
Una pequeña empresa llamada NetSecure Solutions necesita una aplicación web interna para que el equipo técnico pueda registrar incidencias informáticas, asignarlas a distintos técnicos y hacer seguimiento de su resolución.
Un desarrollador del equipo ha creado una primera versión de la aplicación usando:
- PHP
- MySQL
- Apache
- JavaScript
- HTML y CSS
La aplicación funciona, pero ahora surge un problema habitual en muchos proyectos técnicos:
- el sistema debe instalarse también en otro servidor
- otros técnicos tienen que poder mantenerlo
- un responsable debe entender qué incluye el proyecto
- si aparece un error, alguien debe saber cómo revisarlo
- si el desarrollador original no está, el trabajo debe poder continuar
Para evitar depender únicamente de la memoria del autor, el equipo decide crear una documentación técnica completa del proyecto.
¿Qué documentación necesitarían?
En este caso podrían necesitar, por ejemplo:
- un README principal para explicar el proyecto
- una guía de instalación para desplegarlo en otro equipo
- una guía de configuración de la base de datos
- una documentación de estructura del proyecto
- una guía operativa para revisar logs y reiniciar servicios
- una base de incidencias frecuentes
- una memoria técnica para presentar el proyecto a dirección o a un cliente
¿Por qué este caso de uso es bueno para el módulo?
Porque permite ver claramente que:
- no toda la documentación sirve para lo mismo
- un único documento no siempre es suficiente
- el destinatario cambia según el documento
- un proyecto técnico necesita más de un tipo de documentación
Ejemplo de índice
A continuación tienes un índice de ejemplo para la documentación de este proyecto ficticio. Te puede servir para enseñar a los alumnos cómo se organiza un documento técnico amplio.
Índice de ejemplo: Documentación técnica del proyecto “NetSecure Tickets”
1. Introducción
1.1. Descripción general del proyecto
1.2. Objetivo de la aplicación
1.3. Alcance del sistema
1.4. Público al que va dirigida esta documentación
2. Visión general del proyecto
2.1. Problema que resuelve
2.2. Funcionalidades principales
2.3. Tecnologías utilizadas
2.4. Estructura general de funcionamiento
3. Requisitos previos
3.1. Requisitos de hardware
3.2. Requisitos de software
3.3. Versiones recomendadas
3.4. Dependencias necesarias
4. Instalación del entorno
4.1. Instalación de Apache
4.2. Instalación de PHP
4.3. Instalación de MySQL
4.4. Configuración inicial del servidor
4.5. Verificación del entorno
5. Despliegue de la aplicación
5.1. Copia de archivos del proyecto
5.2. Estructura de carpetas
5.3. Configuración de conexión a base de datos
5.4. Importación de la base de datos
5.5. Prueba inicial de funcionamiento
6. Uso básico de la aplicación
6.1. Pantalla principal
6.2. Registro de incidencias
6.3. Consulta de incidencias
6.4. Asignación a técnicos
6.5. Cierre de incidencias
7. Estructura técnica del proyecto
7.1. Organización de archivos
7.2. Archivos principales
7.3. Relación entre frontend y backend
7.4. Base de datos y tablas utilizadas
8. Procedimientos operativos
8.1. Reinicio de servicios
8.2. Revisión de logs
8.3. Copia de seguridad de la base de datos
8.4. Restauración básica
8.5. Comprobaciones de estado
9. Incidencias frecuentes
9.1. Error de conexión a MySQL
9.2. Error 403 o 404 en Apache
9.3. Problemas con permisos de archivos
9.4. Fallos al cargar estilos o scripts
9.5. Errores comunes y solución
10. Mejoras futuras
10.1. Autenticación de usuarios
10.2. Panel de administración
10.3. Exportación de incidencias
10.4. Sistema de avisos por correo
11. Conclusiones
11.1. Resultado obtenido
11.2. Valor del sistema
11.3. Posibles ampliaciones
12. Anexos
12.1. Capturas de pantalla
12.2. Comandos utilizados
12.3. Script SQL inicial
12.4. Referencias técnicas
Versión más corta de índice para un README
Si quieres enseñar también la diferencia entre un documento amplio y un README más simple, podrías poner este otro ejemplo:
Índice de ejemplo de README
- Nombre del proyecto
- Descripción
- Objetivo
- Tecnologías utilizadas
- Requisitos previos
- Instalación
- Configuración
- Ejecución
- Estructura del proyecto
- Problemas frecuentes
- Mejoras futuras
- Autor
