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 {#estados}¶

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_state vs doc_state: el estado operacional del sistema y el estado de la documentación serán metadatos independientes. Un sistema puede estar ⚔️ Probado y 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 {#comprensibilidad}¶

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 solo Demé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 💡 Conceptual a menos que tenga arquitectura detallada
Solo se promociona a 📋 Definido cuando tiene LXC (contenedor ligero de Proxmox) asignado y diseño de integraciones
Solo se promociona a ✅ Desplegado cuando está corriendo en hardware real y verificado
Solo se promociona a 🧪 Validado tras superar un test documentado
Solo se promociona a ⚔️ Probado tras sobrevivir a un fallo real documentado
El badge va debajo del logo, antes del título, centrado
En el mkdocs.yml nav, 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

4. Estructura de página por tipo¶

4.1 Ficha de servicio (`fichas/programas/.md`, `fichas/stacks/.md`, `fichas/sistemas/*.md`)¶

<div align="center">
  <img src="/assets/images/logos/NOMBRE.svg" alt="NOMBRE" width="100">
  <p style="...">tag1 · tag2 · tag3</p>
</div>

<div align="center"><a href="/guia-estilo/#estados"><strong>📋 Definido</strong></a></div>

# NOMBRE — Lo que hace en una frase

Lo que sustituirá del mundo exterior.

## Como usuario
### Qué puedes hacer
### Cómo acceder
| Plataforma | Cómo |
| Navegador | url |
| Ubuntu | cliente |
| Android | app |
| FireTV | app / no aplica |
### Primeros pasos

## Integración con otros servicios de SmallCountry
| Servicio | Relación |

## Servicios que lo hacen posible

??? info "Para el administrador"
    Datos, ZFS, healthcheck, logs, backup, problemas

??? info "Para el arquitecto"
    Relaciones (mermaid), red, Pi-hole, Caddy, Authentik, orquestación

## Captura de pantalla
> 📸 Pendiente de captura

## 🌐 Enlaces de interés

4.2 Manifiesto (`manifiesto/*.md`)¶

# Título del principio

Párrafo de apertura.

---

## El problema que resolvemos
## Cómo lo hacemos posible
### Subtema
### Servicios que lo hacen posible
## En resumen
### Secciones relacionadas

4.3 Compromiso (`compromisos/*.md`)¶

# Para quién va dirigido

Párrafo de apertura.

---

## 1. Primer compromiso
### Cómo lo hacemos posible
### Servicios que lo hacen posible
## 2. Segundo compromiso
## En resumen
### Secciones relacionadas
### Roles

4.4 Página de bloque del manual (`manual/bloques/*.md`)¶

# Bloque X: Nombre

Breve introducción.

---

### [1. Título](enlace)
Resumen de 2-3 líneas.

---

← [Volver al manual](../index.md)

4.5 Rol (`manual/roles/*.md`)¶

# Nombre mitológico — Función

Descripción.

## Relación con el ecosistema (tipo, grupo, panel, compromiso)
## Herramientas y servicios (tabla)
## Flujo de trabajo
## Relación con otros roles (tabla)
## Secciones relacionadas

4.6 Runbook (`manual/runbooks/*.md`)¶

# Runbook: Nombre

Badge de estado.

| Gravedad | Tiempo | Roles |
## Síntomas
## Diagnóstico (checklist)
## Resolución (checklist)
## Verificación
## Prevención

4.7 Proyecto (`proyectos/*.md`)¶

Los proyectos documentan clientes que usarán SmallCountry. Su estructura principal es libre (resumen, marca, producto, sistema tecnológico, formación...) pero deben cumplir:

Requisito	Obligatorio
Badge de estado	Sí
Tiempo verbal según estado	Sí
Logo de SmallCountry inline en cada aparición	Sí
Secciones relacionadas al final	Sí
Back-link (`← Proyectos`)	Sí
Sección de integración con SmallCountry	Sí — siempre al final, antes de Hoja de Ruta

Regla de enlaces externos: los proyectos pueden enlazar al exterior en el cuerpo del texto para servicios, APIs o estándares que no existen en SmallCountry (ej: ORCID, GBIF (red mundial de datos de biodiversidad), Frictionless Data, DataCite, Creative Commons). Si el servicio tiene ficha en SmallCountry, el enlace debe ir a la ficha. No llevan sección ## 🌐 Enlaces de interés (eso es solo para fichas).

Secciones colapsables: como las fichas, los proyectos pueden usar ??? info para secciones de administrador y arquitecto que detallen aspectos técnicos de la integración con SmallCountry que no interesen al lector general.

5. Nomenclatura de dominios internos¶

Todos los servicios de SmallCountry usan el dominio .sc sin sufijo de nodo. El sufijo .<nodo> solo se usa en contextos de administración donde sea necesario distinguir físicamente entre máquinas (SSH, Proxmox UI, métricas por nodo).

Ejemplos correctos: inicio.sc, forgejo.sc, vault.sc, docs.sc
Ejemplos incorrectos: ~~inicio.sc.ra~~, ~~forgejo.sc.ra~~

Fundamento: ADR-007.

6. Reglas de enlaces¶

Origen	Destino permitido
Cualquier página	Fichas (`/fichas/...`)
Cualquier página	Otras páginas internas
Solo fichas	Enlaces externos (sección 🌐)
Nunca	Enlace externo desde manifiesto, compromisos, manual, legal

7. Uso del logo¶

Contexto	Archivo	Color	Tamaño
Cabecera del sitio (header)	`/assets/logo.svg`	Blanco	2rem (CSS)
Intro del index (centrado)	`/assets/logo-accent.svg`	Verde #4CAF50	150px
Inline en texto	`/assets/logo-accent.svg`	Verde #4CAF50	1.2em

Formato inline exacto:

<img src="/assets/logo-accent.svg" style="height:1.2em;vertical-align:text-bottom;" alt=""> **SmallCountry**

El logo inline debe aparecer en todas las apariciones de SmallCountry en el texto.

8. Logos de servicios¶

Todos en assets/images/logos/, formato SVG
Paleta unificada: verde Material (#4CAF50, #2E7D32, #1B5E20, #81C784, #E8F5E9)
Si no existe logo oficial, crear uno simple en la paleta verde
Nombre de archivo: nombre-del-servicio.svg

9. Voz y tono¶

Castellano, no español neutro
Tú, no usted
Presente para lo desplegado, futuro para lo definido, condicional para lo conceptual
Primera persona del plural solo en manifiesto y legal
Tercera persona en la documentación de operaciones

10. Navegación¶

Toda página nueva debe añadirse al mkdocs.yml
Las páginas secuenciales llevan ← [Anterior] | [Siguiente] →
Las páginas independientes llevan ### Secciones relacionadas
Las páginas de bloque del manual llevan ← [Volver al manual](../index.md)

11. Screenshots¶

Sección ## Captura de pantalla antes de 🌐 Enlaces
Si no hay captura real: placeholder PNG + nota 📸 Pendiente de captura
Las capturas se guardan en assets/images/screenshots/

12. Código y comandos¶

Elemento	Sintaxis
Comandos de terminal	```bash
Diagramas de arquitectura	```mermaid
Tablas de datos (LXC, IP, Tier)	Tabla Markdown
Secciones colapsables	`??? info "Título"`

13. Proceso de creación de contenido¶

Clasificar: ¿✅ Desplegado, 📋 Definido o 💡 Conceptual?
Elegir plantilla: según el tipo de página
Escribir: siguiendo la plantilla y el tiempo verbal correcto
Enlazar: solo a fichas desde el cuerpo; externos solo en 🌐
Añadir al nav: actualizar mkdocs.yml
Verificar: mkdocs build --clean sin errores
Commit: con mensaje descriptivo

← Inicio