Excepciones a la guía de estilo de documentación

El Manual de Administración de NorTK VM se adhiere a las directrices de la Guía de Estilo de Documentación para NorTK. No obstante, dado que este manual está orientado a la operación cotidiana de alto nivel mediante interfaces gráficas (Cockpit y virt-manager) y busca facilitar la transición de administradores provenientes de plataformas privativas como VMware vSphere, se establecen cinco excepciones y adaptaciones metodológicas formales.

Adaptación del contrato de cinco bloques para interfaces visuales

El contrato procedimental canónico de NorTK exige comandos exclusivos de terminal en el bloque de procedimiento y comandos de auditoría CLI en el bloque de verificación. En este manual se aplica la siguiente adaptación:

  • Procedimiento visual primario: El paso a paso documenta la interacción directa en la consola web Cockpit o en el gestor de escritorio virt-manager. Las rutas de navegación se expresan mediante el separador mayor que (Menú > Submenú > Acción) y los elementos interactivos se resaltan estrictamente en negrita.

  • Flujo complementario de comandos de terminal: Para no limitar al operador a la interfaz gráfica y habilitar la reproducibilidad por consola o automatización por scripts, cada procedimiento incluye un bloque secundario o nota explicativa con los comandos equivalentes mediante herramientas de línea de comandos como virsh, virt-install o qemu-img.

  • Verificación híbrida: La verificación documenta tanto la confirmación visual en la interfaz (indicador de estado En ejecución, gráficas de telemetría de CPU y memoria en tiempo real, consola VNC/SPICE activa) como el comando determinista de auditoría por terminal para confirmar el estado en libvirt.

Política para capturas de pantalla y recursos gráficos

La norma general prohíbe las capturas de pantalla salvo casos excepcionales. Para NorTK VM se flexibiliza esta regla bajo condiciones estrictas de calidad y pertinencia técnica:

  • Casos autorizados: Se autoriza la inclusión de capturas de pantalla para asistentes paso a paso de creación de máquinas virtuales, cuadros de diálogo de configuración de hardware virtualizado y paneles de asignación de redes o almacenamiento en Cockpit y virt-manager.

  • Encuadre estricto: La captura debe ceñirse con precisión al cuadro de diálogo o panel interactivo relevante. Queda prohibido capturar escritorios completos, barras de tareas del sistema operativo anfitrión o marcos externos del navegador web.

  • Legibilidad y resolución: Antes de realizar la captura, debe ajustarse el tamaño de fuente de la interfaz para garantizar que los textos mantengan una altura de al menos 14 a 16 píxeles. La resolución máxima admitida es de 1920x1080 píxeles.

  • Formato y optimización: Las imágenes se almacenan en source/_static/images/ en formato PNG optimizado mediante herramientas de compresión sin pérdidas como optipng.

  • Accesibilidad: Toda imagen debe incluir obligatoriamente el parámetro :alt: con una descripción exhaustiva del estado y las opciones seleccionadas para usuarios de lectores de pantalla.

  • Prohibición absoluta en salidas textuales: Permanece estrictamente prohibido capturar salidas de terminal, tablas de texto, fragmentos de código XML o archivos de configuración. Todo contenido textual debe redactarse mediante bloques .. code-block::.

Módulos de correspondencia conceptual desde VMware vSphere

A diferencia de los manuales de infraestructura estándar que asumen conocimiento previo del ecosistema KVM/libvirt, este manual incorpora módulos introductorios y tablas comparativas orientadas a tender puentes conceptuales para operadores habituados a VMware:

Concepto en VMware vSphere

Equivalente funcional en NorTK VM

Datastore (VMFS/NFS/vSAN)

Pool de almacenamiento libvirt (directorio, LVM, NFS, iSCSI, Ceph RBD)

vSwitch/Port Group

Puente de Linux (Linux Bridge) u Open vSwitch (OVS)

VMware Tools

Agente invitado QEMU (paquete qemu-guest-agent)

vMotion

Migración en vivo de libvirt (Live Migration con cifrado TLS)

Formato de disco VMDK

Formato QCOW2 (con instantáneas copy-on-write) o formato plano RAW

OVA/OVF

Plantillas base aprovisionadas con Cloud-Init o conversión mediante virt-v2v

Bilingüismo de interfaz y glosa técnica

La documentación se redacta en español técnico normativo conforme al glosario de NorTK. No obstante, reconociendo que la mayoría de los entornos corporativos VMware operan con consolas en idioma inglés y que los administradores asocian términos específicos a dicha nomenclatura:

  • Se incluye la denominación original en inglés entre paréntesis o en glosa comparativa en la primera mención de cada concepto (por ejemplo: instantáneas de disco (snapshots), asignación elástica de memoria (memory ballooning)).

  • En los procedimientos de Cockpit se provee la referencia tanto para interfaces configuradas en español como para sesiones con variables de entorno en inglés.

Clarificación del contexto de sesión en libvirt

En entornos de escritorio convencionales, herramientas como virt-manager pueden conectarse de manera predeterminada a la sesión del usuario ordinario (qemu:///session). En NorTK VM se establece como directiva explícita que toda máquina virtual de producción empresarial debe desplegarse en el contexto del sistema (qemu:///system):

  • Continuidad operativa: Las máquinas virtuales bajo qemu:///system inician automáticamente durante el arranque del hipervisor a través de los servicios del sistema, sin requerir que un operador inicie sesión gráfica interactiva.

  • Integración de red y almacenamiento: Permite la vinculación directa con puentes de red administrados por el sistema y pools de almacenamiento persistentes bajo control de acceso de SELinux en modo Enforcing.

Mandatos inmutables de estilo preservados

Las siguientes reglas de la Guía de Estilo de Documentación para NorTK se mantienen en vigor absoluto y sin excepciones:

  • Directiva cardinal de diagonales: Jamás coloque espacios alrededor de barras diagonales. Escriba siempre palabra/palabra (como kvm/qemu, virtio-net/virtio-blk o activo/pasivo), nunca palabra / palabra.

  • Indentación a tres espacios: Todo bloque anidado y cuerpo de directiva en reStructuredText debe sangrarse a tres espacios exactos.

  • Títulos limpios: Prohibido el uso de paréntesis en títulos y encabezados. En español, los títulos llevan mayúscula únicamente en la letra inicial y en los nombres propios. Queda prohibida la mayúscula sostenida y el estilo titular en inglés (Title Case).

  • Bloques de código: Uso exclusivo de directivas .. code-block:: <lenguaje>. Jamás incluya la opción :caption: en un bloque de código.

  • Erradicación del antropomorfismo: El software y el hardware carecen de conciencia o voluntad. Describa procesos, evaluaciones de condiciones y retornos de estado de manera objetiva.