Guía de estilo de la documentación¶
Esta guía recoge todas las decisiones editoriales, de estructura y de estilo tomadas durante la construcción de esta documentación. Es la referencia para que cualquier persona —o IA— que contribuya mantenga la coherencia del sitio.
1. Filosofía de la documentación¶
SmallCountry es un proyecto en construcción. La documentación debe reflejar honestamente el estado real de cada componente. No describimos como presente lo que aún no existe.
Principios rectores¶
- Honestidad: cada página indica si lo que describe está desplegado, definido o es conceptual
- Consistencia: todas las páginas del mismo tipo siguen la misma estructura
- Autosuficiencia: los enlaces solo salen al exterior desde las fichas; el resto del sitio enlaza internamente
- Comprensibilidad: todo término técnico, acrónimo, nombre de servicio o rol se presenta con una mini-descripción en su primera aparición en cada página. La documentación se escribe para sobrevivir al arquitecto: si él desaparece, el conocimiento no desaparece con él. Cualquier persona —sin conocimientos previos de SmallCountry— debe poder entender cualquier página por sí sola.
2. Clasificación de estado¶
Todo servicio, proceso o componente debe indicar su estado al inicio de la página mediante uno de estos badges, que reflejan su nivel de confianza operacional demostrada, no el tiempo que lleva funcionando.
2.1 Niveles de madurez¶
| Badge | Significado | Criterio de promoción |
|---|---|---|
💡 Conceptual |
Idea, hipótesis o diseño inicial | Nace aquí por defecto |
📋 Definido |
Arquitectura detallada: LXC (contenedor ligero de Proxmox) asignado, playbook previsto, integraciones diseñadas | Tiene diseño completo documentado |
✅ Desplegado |
Corriendo en hardware real, monitorizado | Instalado, corriendo, métricas en Grafana |
🧪 Validado |
Ha superado un test funcional, simulacro o validación explícita | Test documentado con resultado |
⚔️ Probado |
Ha sobrevivido a un fallo real en producción | Incidente real superado documentado |
Doctrina de promoción: los estados no representan tiempo operativo sino confianza operacional demostrada. Un servicio no promociona de ✅ a 🧪 por inercia temporal. Requiere simulacro, test, incidente controlado o validación explícita documentada. No hay promoción automática.
2.2 Niveles de criticidad (Tier)¶
Cada servicio tiene asignado un Tier de criticidad que define cuánto daño produce su fallo:
| Tier | Nombre | Significado | Ejemplos |
|---|---|---|---|
| S | Supervivencia | Su fallo produce daño físico irreversible | Bomba del sótano, Shelly (actuador eléctrico WiFi) 1PM, Geb (energía) |
| A | Crítico | Caída = el ecosistema no funciona | NetBird, Authentik, Pi-hole, Caddy, Proxmox |
| B | Importante | Caída = afecta al día a día | Nextcloud, Immich, Vaultwarden, n8n, farmOS |
| C | Conveniente | Caída = inconveniente, no emergencia | Jellyfin, Kavita, Grocy, Audiobookshelf |
| D | Experimental | Sin impacto operativo | Odoo, Suricata, PostHog, Matomo, Tempo |
Regla doctrinal para Tier D: todo servicio clasificado como Tier D debe tener documentados: fecha de creación, hipótesis que justifica su existencia, criterio claro de promoción a Tier C o superior, y criterio de abandono si la hipótesis no se confirma. Sin esto, el Tier D se convierte en ruido permanente.
2.3 Matriz de criticidad × madurez¶
El cruce de Tier y badge determina la prioridad operacional:
| Badge ↓ / Tier → | S (Supervivencia) | A (Crítico) | B (Importante) | C (Conveniente) | D (Experimental) |
|---|---|---|---|---|---|
💡 Conceptual |
🚨 Diseñar ya | 🔴 Urgente | 🟡 Priorizar | 🟢 Normal | 🟢 Normal |
📋 Definido |
🚨 Prioridad máxima | 🔴 Alta prioridad | 🟡 Media | 🟢 Baja | 🟢 Baja |
✅ Desplegado |
🚨 Monitorizar 24/7 | 🔴 Monitorizar 24/7 | 🟡 Monitorizar | 🟢 Monitorizar | 🟢 Monitorizar |
🧪 Validado |
🔴 Obligatorio test periódico | 🔴 Obligatorio test periódico | 🟡 Test recomendado | 🟢 Opcional | 🟢 Opcional |
⚔️ Probado |
🟢 Estado ideal | 🟢 Estado ideal | 🟢 Estado ideal | 🟢 Excesivo | 🟢 Excesivo |
2.4 Metadatos futuros¶
En el futuro, cada ficha incorporará metadatos estructurados para análisis automático de dependencias y riesgos:
system_statevsdoc_state: el estado operacional del sistema y el estado de la documentación serán metadatos independientes. Un sistema puede estar⚔️ Probadoy tener documentación desactualizada. Por ahora, el badge refleja la intersección de ambos.depends_on: lista de servicios de los que depende. Ej: NetBird →[authentik, dns, energia].degrades_to: modo degradado cuando el servicio falla. Ej: IA →[modelo-ligero-cpu, documentación-estática].spof: puntos únicos de fallo si este servicio cae. Ej: Authentik →[todos los servicios con OIDC (protocolo de autenticación OpenID Connect)].blast_radius: servicios afectados si este falla.
Estos metadatos permitirán en el futuro visualizaciones de dependencias, simulaciones de fallo y análisis de degradación cruzada. Se diseñan ahora para añadirse sin reescribir la documentación existente.
2.5 Inmovilización de versiones¶
A partir del 11 de mayo de 2026, todas las versiones de software de SmallCountry quedan bloqueadas a las versiones estables disponibles en esa fecha.
Doctrina:
- Base inmutable: todo el desarrollo se construye sobre versiones conocidas y verificadas
- Actualizaciones controladas: ningún servicio se actualiza automáticamente. No se usa :latest en imágenes Docker
- Proceso explícito: cada cambio de versión requiere PR en Forgejo, revisión, prueba en staging y aprobación
- Trazabilidad: el historial de versiones se documenta en operaciones/versiones.md y en cada ficha individual
Cada ficha de servicio muestra la versión bloqueada con un badge 📌 vX.Y · YYYY-MM-DD debajo del badge de estado. La lista completa de versiones está en operaciones/versiones.md.
2.6 Comprensibilidad universal¶
La documentación de SmallCountry se escribe para que cualquier persona —sin conocimientos técnicos previos y sin acceso al arquitecto— pueda entenderla al 100%. Esto no es una recomendación: es un requisito de supervivencia del proyecto.
Reglas:
-
Acrónimos: la primera vez que aparece un acrónimo en una página, se escribe completo con la sigla entre paréntesis. Ej:
Infraestructura como Código (IaC (Infraestructura como Código)),Sistema de Archivos (ZFS (sistema de archivos con integridad de datos)) -
Nodos y servidores: la primera mención de Ra (servidor principal de SmallCountry), Horus (servidor secundario con GPU para IA), Geb (gateway energético Victron en la finca) o Thoth (Raspberry Pi árbitro del clúster y backup offsite) en cada página incluye su rol. Ej:
Ra (servidor principal),Horus (servidor secundario con GPU (procesador gráfico para IA) para IA) -
Servicios: la primera mención de un servicio en una página incluye una mini-descripción. Ej:
Nextcloud (archivos y calendario) -
Roles: toda referencia a un rol usa el formato compuesto completo:
Deméter — Cultivos y cosechas(no soloDeméter) -
Términos técnicos: si un término puede no ser de dominio público (
bridge,proxy,DNS), la primera aparición en cada página incluye una explicación breve
El glosario canónico con las mini-descripciones aprobadas para cada término está en operaciones/glosario.md.
Reglas¶
- Una ficha recién creada nace como
💡 Conceptuala menos que tenga arquitectura detallada - Solo se promociona a
📋 Definidocuando tiene LXC (contenedor ligero de Proxmox) asignado y diseño de integraciones - Solo se promociona a
✅ Desplegadocuando está corriendo en hardware real y verificado - Solo se promociona a
🧪 Validadotras superar un test documentado - Solo se promociona a
⚔️ Probadotras sobrevivir a un fallo real documentado - El badge va debajo del logo, antes del título, centrado
- En el
mkdocs.ymlnav, opcionalmente se puede añadir el emoji junto al nombre
3. Tiempos verbales¶
| Estado | Tiempo verbal | Ejemplo |
|---|---|---|
⚔️ Probado |
Presente de indicativo | "Nextcloud es el centro de archivos de SmallCountry" |
🧪 Validado |
Presente de indicativo | "Nextcloud es el centro de archivos de SmallCountry" |
✅ Desplegado |
Presente de indicativo | "Nextcloud es el centro de archivos de SmallCountry" |
📋 Definido |
Futuro simple | "Nextcloud será el centro de archivos de SmallCountry" |
💡 Conceptual |
Condicional / futuro | "Odoo podría ser el backend económico de la finca" |
Esto aplica a: - La descripción principal de cada ficha - Las secciones de "Cómo lo hacemos posible" en compromisos y manifiesto - Las guías de usuario dentro de las fichas - Los flujos de trabajo descritos
No aplica a: - Los principios (son atemporales) - El aviso legal - Los nombres de los servicios