32. Publicación, búsqueda, navegación y accesibilidad de la documentación

32.1 Introducción

Una documentación puede estar correctamente escrita y aun así ser poco útil si nadie la encuentra, si no sabe si está actualizada, si la navegación es confusa o si no puede accederse desde los dispositivos y condiciones necesarias.

Publicar documentación no significa solamente subir archivos. Implica definir audiencia, ubicación, permisos, estructura, búsqueda, navegación, accesibilidad, versiones y mecanismos de actualización.

En este tema veremos cómo hacer que la documentación sea visible, encontrable, navegable y usable para las personas que la necesitan.

32.2 Qué significa publicar documentación

Publicar documentación significa ponerla a disposición de su audiencia en un lugar adecuado, con formato apropiado y con permisos correctos. Puede publicarse en un sitio web, wiki, repositorio, portal interno, ayuda integrada al sistema o documentación generada automáticamente.

La publicación debe considerar quién necesita el contenido. Un manual de usuario requiere acceso sencillo. Una guía interna de operación puede requerir autenticación. La documentación de seguridad puede necesitar acceso restringido.

32.3 Documentación encontrable y accesible

La imagen muestra un portal de documentación con publicación, búsqueda, navegación, categorías, accesibilidad, versiones, permisos y enlaces relacionados. La idea central es que la documentación no solo exista, sino que pueda encontrarse y usarse con facilidad.

32.4 Ubicación

La ubicación de la documentación debe ser conocida. Si los documentos están repartidos entre correos, carpetas personales, wikis antiguas y repositorios sin enlaces, el equipo pierde tiempo buscando y puede usar información desactualizada.

Conviene definir ubicaciones oficiales: repositorio para documentación técnica ligada al código, portal para usuarios, wiki para procedimientos internos o sitio estático para documentación del producto.

32.5 Estructura de navegación

La navegación organiza el contenido para que el lector avance por tema, tarea o rol. Puede incluir menús, categorías, rutas, índices, enlaces de anterior y siguiente, migas de navegación y páginas de inicio por audiencia.

Una buena navegación evita que el usuario tenga que conocer la estructura interna del equipo para encontrar información. Debe reflejar necesidades de consulta, no solo organigramas.

32.6 Búsqueda

La búsqueda es esencial cuando la documentación crece. Para que funcione bien, los documentos necesitan títulos claros, términos consistentes, contenido indexable y ausencia de duplicados confusos.

También conviene usar palabras que la audiencia buscaría. Un usuario puede buscar "cancelar turno", mientras que el equipo técnico podría llamar a la misma acción "anular reserva". La terminología debe considerar esas diferencias o incluir sinónimos controlados.

32.7 Enlaces relacionados

Los enlaces relacionados ayudan a pasar de una explicación a contenido complementario. Una guía de instalación puede enlazar configuración, solución de problemas y despliegue. Una documentación de API puede enlazar autenticación, errores y ejemplos.

Los enlaces deben ser relevantes y mantenerse. Enlazar todo con todo genera ruido. Enlazar lo necesario mejora navegación y reduce duplicación.

32.8 Páginas de inicio por audiencia

Cuando existen varias audiencias, puede ser útil crear páginas de inicio específicas: para usuarios finales, desarrolladores, operación, soporte o nuevos integrantes. Cada página reúne los enlaces más importantes para ese rol.

Esto evita que una persona nueva tenga que recorrer todo el portal para descubrir por dónde empezar.

32.9 Accesibilidad

La accesibilidad busca que la documentación pueda ser usada por la mayor cantidad de personas posible. Incluye estructura semántica, contraste suficiente, texto alternativo en imágenes, navegación con teclado, lenguaje claro y contenido que no dependa solo de color.

También implica considerar dispositivos y contextos. Una guía operativa puede necesitar leerse en una pantalla pequeña durante un incidente. Un manual de usuario puede ser consultado por personas con distintos niveles de experiencia digital.

32.10 Control de permisos

No toda documentación debe ser pública. Algunas guías internas, documentos de seguridad, credenciales, procedimientos sensibles o información de clientes requieren control de acceso.

La publicación debe equilibrar disponibilidad y seguridad. Restringir demasiado puede impedir trabajo; publicar demasiado puede exponer riesgos. La decisión debe basarse en audiencia y sensibilidad del contenido.

32.11 Versiones publicadas

Cuando un producto tiene varias versiones, la documentación publicada debe indicar a cuál corresponde. Esto es fundamental en APIs, productos instalables, bibliotecas y sistemas con clientes en versiones distintas.

La navegación debe permitir elegir versión y advertir cuando una versión está obsoleta. El lector debe saber si está viendo documentación actual o histórica.

32.12 Metadatos visibles

En documentos importantes conviene mostrar metadatos: fecha de última actualización, versión, responsable, estado o audiencia. Esto ayuda a evaluar confiabilidad.

Un procedimiento operativo sin fecha puede generar dudas. Un manual de usuario sin versión puede no coincidir con la interfaz actual. Los metadatos reducen incertidumbre.

32.13 Tabla de criterios de publicación

32.14 Documentación integrada al producto

Algunas ayudas pueden integrarse dentro del propio sistema: textos de ayuda, enlaces contextuales, mensajes, tooltips, recorridos guiados o centros de ayuda. Esto reduce la distancia entre tarea y documentación.

La ayuda integrada debe ser breve y enlazar a documentación más completa cuando sea necesario. No conviene saturar la interfaz con explicaciones largas.

32.15 Medición de uso

Medir uso de documentación puede mostrar qué páginas se consultan, qué búsquedas fallan, qué temas generan dudas y qué documentos no se usan. Esta información ayuda a mejorar estructura y contenido.

También puede compararse con consultas de soporte. Si muchas personas preguntan algo que ya está documentado, quizá el documento no se encuentra o no está escrito de forma clara.

32.16 Errores frecuentes

Al publicar documentación suelen aparecer estos errores:

• Publicar documentos sin una ubicación oficial conocida.
• Organizar navegación según estructura interna del equipo y no según necesidades del lector.
• No tener búsqueda o usar títulos poco buscables.
• No controlar permisos de documentación sensible.
• No indicar versión o fecha de actualización.
• Depender solo de imágenes sin texto alternativo.
• No revisar enlaces y páginas obsoletas.

32.17 Qué debes recordar de este tema

• La documentación debe publicarse donde su audiencia pueda encontrarla.
• La navegación debe responder a tareas, temas y roles.
• La búsqueda depende de buenos títulos, términos consistentes y contenido indexable.
• Los permisos deben proteger documentación sensible sin bloquear trabajo necesario.
• La accesibilidad mejora el uso para más personas y contextos.
• Las versiones y metadatos visibles reducen dudas sobre vigencia.
• Medir uso y consultas ayuda a mejorar la documentación publicada.

32.18 Conclusión

Publicar documentación implica mucho más que almacenarla. Para que sea útil, debe poder encontrarse, navegarse, comprenderse y usarse con facilidad por la audiencia adecuada.

En el próximo tema estudiaremos el mantenimiento de la documentación: obsolescencia, deuda documental y mejora continua.