Documentación técnica

La documentación técnica es, desde el punto de vista de la arquitectura de la información, uno de los tipos de contenido más exigentes. Es extensa, altamente estructurada, referenciada frecuentemente desde fuentes externas, requiere versionado y su audiencia la consume de forma radicalmente distinta a como un lector consume un artículo de blog: no secuencialmente, sino como referencia, buscando información específica en el momento en que la necesita.

Qué distingue a la documentación de otros tipos de contenido

Es normativa, no editorial. La documentación no expresa opiniones ni narra experiencias. Define cómo funciona algo, cómo se usa, cuáles son sus parámetros, qué errores pueden ocurrir. Su autoridad es de referencia, no de perspectiva.

Se actualiza sin que la actualización sea un evento. Cuando se actualiza un artículo de blog, puede tener sentido comunicarlo. Cuando se actualiza la documentación, simplemente está actualizada. La fecha de publicación es irrelevante; lo relevante es la versión del software o la especificación que documenta.

Es consumida como referencia. Los usuarios de documentación técnica raramente la leen de principio a fin. Buscan un término específico, una función, un ejemplo de código. La búsqueda interna y la navegación por el índice son más importantes que la navegación secuencial.

Tiene dependencias internas complejas. Un artículo de documentación puede referenciar a docenas de otros artículos. Las dependencias entre secciones son densas y bidireccionales.

Es enlazada externamente de forma permanente. Los desarrolladores guardan enlaces a páginas de documentación específicas, los foros los citan, los tutoriales los referencian. La estabilidad de las URLs de documentación es crítica: un enlace roto en documentación técnica es una interrupción directa en el flujo de trabajo de un profesional.

Estructura de URLs para documentación

Sin versionado

/documentacion/nombre-del-componente/
/docs/nombre-del-componente/
/documentacion/guia-de-inicio/
/documentacion/referencia/nombre-de-funcion/

Adecuada cuando solo existe una versión activa de la documentación. Es la estructura más simple y la que produce URLs más estables.

Con versionado explícito

/documentacion/v3/nombre-del-componente/
/documentacion/v2/nombre-del-componente/
/documentacion/v1/nombre-del-componente/

Adecuada cuando es necesario mantener documentación de versiones anteriores accesible simultáneamente. Esto es habitual en proyectos de software con múltiples versiones en uso activo (sistemas operativos, frameworks, bibliotecas con ciclos de soporte largo).

La versión actual sin número de versión: Es una práctica habitual mantener la URL sin versión para la versión actual y usar URLs con versión para las anteriores:

/documentacion/nombre/          ← versión actual (sin versión en URL)
/documentacion/v2/nombre/       ← versión anterior
/documentacion/v1/nombre/       ← versión más antigua

Cuando salga la versión 4, la URL /documentacion/nombre/ pasa a documentar la v4, y la v3 se archiva en /documentacion/v3/nombre/. Esto evita que todos los enlaces externos queden obsoletos con cada nueva versión.

Estructura interna de la documentación

La documentación técnica suele organizarse en secciones con propósito distinto:

Guía de inicio (Getting Started): El punto de entrada para nuevos usuarios. Debe ser corta, práctica y llevar al usuario a un resultado funcional lo antes posible. Es el contenido más leído de cualquier documentación.

Guías temáticas (Guides / How-to): Explicaciones orientadas a tareas. “Cómo hacer X”, “Cómo configurar Y”. Tienen mayor extensión y mayor profundidad que la guía de inicio.

Referencia (Reference): Documentación exhaustiva de todas las funciones, parámetros, opciones de configuración, valores de retorno y errores. Es el contenido más técnico y denso, consumido principalmente como referencia puntual.

Conceptos (Concepts / Explanation): Explicaciones del modelo conceptual del sistema: cómo funciona internamente, por qué se diseñó así, qué problemas resuelve. Ayuda a los usuarios a construir un modelo mental del sistema.

Tutoriales: Secuencias paso a paso orientadas al aprendizaje. A diferencia de las guías, los tutoriales llevan al usuario por un camino predefinido con un objetivo de aprendizaje explícito.

Esta división, conocida como el framework Diátaxis (desarrollado por Daniele Procida), es una referencia ampliamente adoptada en documentación técnica.

Versionado y mantenimiento

La documentación técnica envejece con el software que documenta. Gestionar este envejecimiento es uno de los mayores retos operativos:

Indicar claramente la versión documentada. Cada página de documentación debe indicar a qué versión del software corresponde y, si existe versión más reciente, ofrecer un enlace a la documentación actualizada.

Marcar documentación obsoleta. Las páginas de documentación de versiones antiguas deben indicarlo claramente. Un usuario que llega a documentación de una versión obsoleta sin saberlo comete errores.

No eliminar documentación de versiones anteriores. Los usuarios con versiones antiguas en producción necesitan esa documentación. Los enlaces externos apuntan a ella. Eliminarla es costoso para los usuarios y genera enlaces rotos.

Gestionar las redirecciones con precisión. Cuando una función se renombra, se refactoriza o se elimina entre versiones, la URL antigua debe redirigir a la documentación más relevante disponible (la nueva función, la guía de migración, la página de la versión anterior).

Búsqueda interna en documentación

En documentación técnica, la búsqueda interna no es opcional. Los usuarios de documentación buscan de forma activa: saben lo que necesitan, no lo encuentran navegando, buscan.

La búsqueda en documentación debe:

  • Mostrar resultados con fragmento contextual (el párrafo donde aparece el término buscado).
  • Poder filtrar por versión y por tipo de contenido (referencia, guía, tutorial).
  • Ser tolerante con variaciones ortográficas y sinónimos técnicos.
  • Priorizar los resultados de la versión actual sobre versiones anteriores.

Para profundizar