Guía de Estilo de Documentación para NorTK
Estándar de Documentación Modular, Rigor Didáctico y Soberanía Digital para Infraestructura Crítica.
Introducción
En NorTK diseñamos, desplegamos y operamos infraestructura crítica empresarial sobre cimientos de Software Libre: sistemas operativos GNU/Linux Enterprise, clústeres de virtualización KVM, bases de datos PostgreSQL, almacenamiento distribuido, redes y Kubernetes bare-metal. En este entorno de misión crítica, la documentación es un entregable de ingeniería indispensable para la reproducibilidad operativa, la soberanía tecnológica y la mitigación de fallos en producción.
Esta guía de estilo consolida las directrices normativas para la redacción, arquitectura, tipografía y validación de toda la documentación técnica de NorTK.
Pilares fundamentales
El marco documental de NorTK se nutre de la convergencia de tres referentes de la industria:
Guía de estilo de GNU Press de la Free Software Foundation: Didáctica basada en hechos con demostración práctica inmediata, gestión de la carga cognitiva, fundamentación empírica de juicios de valor, identificación sistemática de trampas operativas y accesibilidad estructural.
Documentación de Red Hat Enterprise Linux 10: Arquitectura modular estricta dividida en concepto, procedimiento, referencia y ensamblaje, con procedimientos deterministas de verificación obligatoria y endurecimiento para misión crítica.
Guía de estilo de IBM Press: Rigor editorial y gramatical, voz activa, imperativo directo, erradicación tajante del antropomorfismo, taxonomía temática, convenciones tipográficas de interfaz y anatomía de cuatro componentes para mensajes de error.
Licencia
Esta documentación se distribuye bajo los términos de la Licencia de Documentación Libre de GNU (GNU Free Documentation License), Versión 1.3 o cualquier versión posterior publicada por la Free Software Foundation. Consulte el archivo COPYING o LICENSE en el repositorio para los términos completos.
Contenido de la guía:
- 1. Principios editoriales y filosofía
- 1.1. Propósito y audiencia objetivo
- 1.2. Didáctica basada en hechos
- 1.3. Gestión de la carga cognitiva
- 1.4. Fundamentación empírica de juicios de valor
- 1.5. Voz activa y persona gramatical
- 1.6. Normas ortográficas de capitalización en títulos
- 1.7. Erradicación del antropomorfismo
- 1.8. Identificación proactiva de trampas operativas
- 1.9. Accesibilidad estructural y coherencia auditiva
- 2. Arquitectura modular de documentos
- 3. Procedimientos operativos y verificación
- 3.1. El contrato de cinco bloques
- 3.2. Bloque 1: propósito y contexto operativo
- 3.3. Bloque 2: prerrequisitos
- 3.4. Bloque 3: procedimiento paso a paso
- 3.5. Bloque 4: verificación determinista
- 3.6. Bloque 5: recursos adicionales
- 3.7. Manejo de privilegios y prompts de terminal
- 3.8. Plantilla canónica de procedimiento
- 4. Convenciones de interfaz y tipografía
- 4.1. Notación formal de sintaxis de comandos
- 4.2. Elementos tipográficos de la línea de comandos
- 4.3. Interfaces en modo texto y gráficas
- 4.4. Nomenclatura y acciones de teclado
- 4.5. Unidades de medida y prefijos binarios frente a decimales
- 4.6. Formatos de fecha, hora y redes
- 4.7. Reglas para capturas de pantalla y recursos gráficos
- 5. Mensajería del sistema y gestión de errores
- 5.1. La anatomía canónica de cuatro partes
- 5.2. Componente 1: identificador de mensaje
- 5.3. Componente 2: texto del mensaje
- 5.4. Componente 3: explicación técnica
- 5.5. Componente 4: respuesta del operador
- 5.6. Tipos y niveles de severidad de mensajes
- 5.7. Uso disciplinado de admoniciones en Sphinx
- 5.8. Catálogo de trampas comunes
- 6. Estándar de marcado reStructuredText
- 7. Glosario y terminología técnica
Control de versiones: