Documentación y buenas prácticas en Linux¶

La documentación es una de las habilidades más infravaloradas pero más críticas para un sysadmin. Un sistema bien documentado es mantenible, escalable y recuperable, incluso bajo presión o cuando no estás presente.

En este módulo aprenderás qué documentar, cómo hacerlo y con qué mentalidad, para trabajar como un sysadmin profesional y evitar dependencias de memoria o personas.

Introducción / Concepto principal¶

La documentación no es solo “apuntar comandos”. Es el conocimiento operativo del sistema expresado de forma clara y reutilizable.

Documentar sirve para:

• Reducir errores repetidos
• Acelerar troubleshooting
• Facilitar traspasos de tareas
• Recuperarse de incidentes
• Dormir mejor 💤

Un sistema sin documentación es un sistema frágil.

Qué debe documentar un sysadmin¶

Información esencial¶

• Arquitectura del sistema
• Versiones de sistema operativo
• Servicios activos
• Puntos críticos
• Dependencias externas

Ejemplo mínimo documentado¶

Servidor: web-prod-01
OS: Ubuntu 22.04 LTS
Servicios: nginx, php-fpm, mysql
Puertos abiertos: 80, 443
Backups: diarios a /backups + remoto

Documenta lo que otro sysadmin necesitaría saber para sobrevivir sin ti.

Documentación técnica práctica¶

Comandos y procedimientos¶

• Instalación de servicios
• Configuración clave
• Rutas importantes
• Comandos de recuperación

# Reinicio seguro de nginx
systemctl reload nginx

# Ver logs principales
journalctl -u nginx

Casos de uso reales¶

• “Cómo recuperar el servicio si falla”
• “Cómo añadir un usuario”
• “Cómo restaurar un backup”

La documentación útil nace de incidentes reales.

Arquitectura y flujos¶

Diagramas simples (texto)¶

Usuario
  |
  v
Nginx
  |
  v
PHP-FPM
  |
  v
MySQL

Checklists operativos¶

[ ] Backup verificado
[ ] Servicio activo tras reboot
[ ] Logs sin errores críticos
[ ] Permisos correctos

No todo necesita dibujos complejos: claridad > estética.

Dónde y cómo documentar¶

Lugares habituales¶

• Repositorios Git (Markdown)
• Wikis internas
• README técnicos
• Archivos .md junto a scripts

Buenas prácticas de formato¶

• Markdown claro
• Títulos consistentes
• Código separado en bloques
• Lenguaje directo y sin ambigüedades

# ✅ Bien documentado
# ❌ Evita frases como: "esto funciona así porque sí"

Puntos críticos / Errores comunes¶

• Documentar solo al final (si hay tiempo)
• Guardar documentación en sitios personales
• Usar lenguaje ambiguo
• No actualizar tras cambios
• Documentar “qué” pero no “por qué”

Consejo: la documentación se mantiene, no se escribe una vez

Ejercicios prácticos¶

1. Documentar un servicio instalado¶

Crea un archivo servicio-nginx.md con:

- Objetivo del servicio
- Puertos
- Configuración clave
- Logs
- Comando de restart

2. Crear checklist de mantenimiento¶

- Estado de servicios
- Espacio en disco
- Backups
- Actualizaciones pendientes

Mentalidad¶

• Documenta como si fueras a desaparecer mañana
• Piensa en el yo del futuro
• Menos texto, más claridad
• Documentar es parte del trabajo, no un extra
• La mejor documentación evita tickets

Resumen¶

• Documentar es una habilidad técnica crítica
• Todo sistema necesita contexto escrito
• Los procedimientos ahorran tiempo y errores
• Markdown + Git = documentación viva
• Un sysadmin profesional deja huella, no dependencia

Siguiente paso¶

El siguiente módulo será una referencia esencial:

Cheatsheet de Linux para sysadmins 1-cheatsheet.md

Donde encontrarás:

• Comandos rápidos
• Sintaxis esencial
• Atajos de uso diario
• Recordatorios para producción