Com fer documentació tècnica d'instal·lacions
Instal·lar un servei és només la meitat de la feina; l'altra meitat és deixar-ho documentat perquè es pugui reproduir, mantenir i revertir. Un bon document d'instal·lació és el que permet que una altra persona (o tu mateix d'aquí a sis mesos) posi en marxa el servei sense haver-te de preguntar res.
La prova de foc
Un document d'instal·lació és bo si una persona diferent de qui el va escriure pot seguir-lo de dalt a baix, en una màquina neta, i acabar amb el servei funcionant i verificat. Si cal "saber-ne un cop més", encara no està acabat.
Els quatre principis
| Principi | Què vol dir |
|---|---|
| Reproductibilitat | Qualsevol pot obtenir el mateix resultat seguint els passos: comandes exactes, versions concretes, rutes completes. |
| Claredat | S'entén sense context previ: objectiu, requisits i resultat esperat de cada pas. |
| Traçabilitat / versionat | El document té versió, data i autor, i es guarda amb control de versions (Git). Els canvis queden registrats. |
| Seguretat | Mai s'hi escriuen contrasenyes, claus ni secrets. Es referencien (gestor de secrets, .env, vault) i es documenta on són, no quins són. |
Anatomia d'un document d'instal·lació
Un document d'instal·lació complet segueix sempre aquesta seqüència de seccions:
---
config:
theme: base
themeVariables:
background: "#FFFFFF"
primaryTextColor: "#1F2937"
lineColor: "#64748B"
primaryColor: "#e0e7ff"
primaryBorderColor: "#2563EB"
---
flowchart TD
A["1 · Portada i metadades"] --> B["2 · Objectiu i abast"]
B --> C["3 · Requisits previs"]
C --> D["4 · Arquitectura i diagrama"]
D --> E["5 · Procediment d'instal·lació"]
E --> F["6 · Configuració"]
F --> G["7 · Verificació i proves"]
G --> H["8 · Còpia de seguretat i rollback"]
H --> I["9 · Manteniment i operació"]
I --> J["10 · Resolució de problemes"]
J --> K["11 · Annexos i referències"]| # | Secció | Què hi ha de constar |
|---|---|---|
| 1 | Portada i metadades | Títol, autor, data, versió, estat (esborrany/validat) i històric de canvis. |
| 2 | Objectiu i abast | Què s'instal·la i per a què; què queda fora de l'abast. |
| 3 | Requisits previs | Sistema operatiu i versió, maquinari/recursos, xarxa (IP, VLAN, ports), permisos i dependències. |
| 4 | Arquitectura i diagrama | Esquema de la solució: hosts, IP, ports, fluxos. Un diagrama val més que un paràgraf. |
| 5 | Procediment d'instal·lació | Passos numerats i reproducibles, amb les comandes exactes i el resultat esperat de cadascun. |
| 6 | Configuració | Fitxers de configuració (amb ruta completa), paràmetres i el perquè de cada valor important. |
| 7 | Verificació i proves | Com comprovar que funciona (comandes de test, sortida esperada, prova des d'un client). |
| 8 | Còpia de seguretat i rollback | Què cal salvar abans, i com desfer la instal·lació si surt malament. |
| 9 | Manteniment i operació | Arrencada/aturada del servei, logs, actualitzacions, monitoratge. |
| 10 | Resolució de problemes | Errors freqüents → causa → solució (enllaça amb la cheat sheet de diagnòstic). |
| 11 | Annexos i referències | Taules d'inventari, documentació oficial, RFC i enllaços. |
Com documentar un pas: de malament a excel·lent
El cor del document són els passos. Aquest exemple mostra com evoluciona un mateix pas (instal·lar un servidor DHCP) fins a ser professional:
Plantilla llesta per copiar
Copia aquesta estructura com a punt de partida de qualsevol document d'instal·lació (Markdown):
# Instal·lació de <SERVEI> a <SISTEMA>
| Camp | Valor |
|------|-------|
| Autor | Nom Cognom |
| Data | AAAA-MM-DD |
| Versió | 1.0 |
| Estat | Esborrany / Validat |
## 1. Objectiu i abast
Què s'instal·la i per a què. Què queda fora de l'abast.
## 2. Requisits previs
- Sistema operatiu i versió: ...
- Recursos (CPU/RAM/disc): ...
- Xarxa: IP, màscara, passarel·la, VLAN, ports a obrir.
- Permisos i dependències: ...
## 3. Arquitectura
Diagrama i taula d'inventari (hosts, IP, rols, ports).
## 4. Procediment d'instal·lació
1. Pas amb la comanda exacta.
$ comanda --opcio
Resultat esperat: ...
2. Pas següent...
## 5. Configuració
Fitxer `/ruta/completa/config`:
parametre = valor # per què
## 6. Verificació
- Comanda de test i sortida esperada.
- Prova des d'un client.
## 7. Còpia de seguretat i rollback
- Què cal salvar abans.
- Passos per desfer la instal·lació.
## 8. Manteniment
Arrencada/aturada, logs, actualitzacions, monitoratge.
## 9. Resolució de problemes
| Símptoma | Causa | Solució |
|----------|-------|---------|
## 10. Referències
- Documentació oficial, RFC, enllaços.
## Històric de canvis
| Versió | Data | Canvis |
|--------|------|--------|
| 1.0 | AAAA-MM-DD | Versió inicial. |
Exemple complet
Tens un document d'instal·lació sencer i ben fet aplicant tota aquesta estructura a la pàgina Exemple: documentació d'un DHCP. Fes-lo servir com a model.
Bones pràctiques
Comandes i sortides
- Posa les comandes en blocs de codi, mai en captures de pantalla (no es poden copiar ni cercar).
- Distingeix la comanda de la sortida esperada.
- Marca clarament què s'executa com a root (
sudo/#) i què com a usuari ($). - Usa rutes absolutes i versions concretes (
Ubuntu 24.04,isc-dhcp-server 4.4), no "l'última versió".
Diagrames com a codi (diagrams-as-code)
Fes els esquemes amb Mermaid o draw.io en lloc d'imatges estàtiques: es versionen amb Git, es modifiquen fàcilment i queden nítids en mode clar i fosc. Inclou sempre IP, ports i sentit dels fluxos.
Credencials i secrets — MAI al document
No escriguis mai contrasenyes, claus privades ni tokens al document. Documenta on es guarden (gestor de secrets, .env fora del repositori, vault) i qui hi té accés. Un document tècnic sovint s'acaba compartint o publicant: un secret escrit hi queda per sempre.
Taula d'inventari (exemple)
Inclou sempre una taula que identifiqui els elements de la instal·lació:
| Host | IP | VLAN | Rol | Ports |
|---|---|---|---|---|
| srv-dhcp01 | 10.0.20.5 | 20 | Servidor DHCP | 67/UDP |
| srv-dns01 | 10.0.10.8 | 10 | Servidor DNS | 53/UDP-TCP |
Versionat i historial
Guarda la documentació amb Git (al costat de la configuració, si pots) i mantén un historial de canvis (data, versió i què has canviat), com fa el Full de versions d'aquest mòdul. Segueix un esquema clar de versions (per exemple, major.minor).
Eines recomanades
- Redacció: Markdown + MkDocs Material (el mateix que fa servir aquest web).
- Diagrames: Mermaid (integrat a MkDocs) i draw.io / diagrams.net.
- Captures de terminal reproduïbles: asciinema per gravar sessions de consola.
- Control de versions: Git + una forge (GitHub/GitLab) per revisar canvis amb pull requests.
- Estil i estructura: el marc Diátaxis (distingeix tutorials, guies, referència i explicació) i les guies d'estil de Google o Microsoft.
Checklist de qualitat
Abans de donar per validat un document d'instal·lació, comprova que:
- Té títol, autor, data, versió i historial de canvis.
- L'objectiu i l'abast són clars.
- Els requisits previs (SO, xarxa, permisos, dependències) hi consten.
- Hi ha un diagrama i una taula d'inventari (hosts, IP, ports).
- Els passos són numerats, amb comandes exactes i resultat esperat.
- Els fitxers de configuració apareixen amb la ruta completa.
- Hi ha una secció de verificació que demostra que funciona.
- Hi ha còpia de seguretat i rollback.
- No hi ha cap secret escrit (contrasenyes, claus, tokens).
- Una persona diferent l'ha pogut seguir sense ajuda.
AC0375 — Miniactivitat: documenta una instal·lació
Tria un dels serveis del mòdul que ja hagis instal·lat (DHCP, DNS, web, FTP o correu) i redacta'n el document d'instal·lació complet seguint la plantilla d'aquesta pàgina. Ha d'incloure el diagrama, la taula d'inventari, els passos amb comandes i verificació, el rollback i el checklist de qualitat superat. Després, intercanvia el document amb un company i que intenti reproduir la instal·lació en una màquina neta: anota què li ha faltat o no ha entès i corregeix-ho.