Cómo crear un portal de documentación técnica con versionado y búsqueda facetada usando módulos contribuidos de Drupal

Un cliente nos escribió el lunes a las 8:14 con un fuego típico: un usuario había seguido la guía de instalación de la v2.3 sobre un producto que ya iba por la v3.1, rompió la base de datos y exigía explicaciones. La guía estaba en GitBook, sin etiqueta visible de versión. Ese día decidieron mover la documentación a un sitio que controlasen ellos.

Si has llegado hasta aquí probablemente arrastras algo parecido: un Read the Docs que nadie en marketing puede editar, un Notion público que tu cliente enterprise no acepta por compliance, o PDFs que envejecen mal en un Drive. La buena noticia es que Drupal cubre este caso con módulos contribuidos, sin desarrollo a medida. Te cuento cómo lo montamos cuando nos llega el encargo.

Por qué Drupal y no una herramienta especializada

Read the Docs, GitBook o Docusaurus hacen bien lo suyo. El problema aparece cuando tu documentación necesita convivir con el resto del negocio.

Si tu portal de docs tiene que compartir login con el área de clientes, respetar permisos por contrato, mostrar contenido distinto según el plan contratado y aparecer bajo el mismo dominio que el blog corporativo, las plataformas SaaS empiezan a estorbar. Acabas con dos identidades, dos buscadores y un proxy reverso que se rompe cada seis meses.

Con Drupal todo vive bajo el mismo techo. Y cuando dentro de dos años decides añadir una academia o un foro de comunidad, no migras nada: extiendes lo que ya tienes.

Modelar el contenido antes de tocar un módulo

El error más caro en estos proyectos es lanzarse a instalar módulos antes de dibujar los tipos de contenido en un papel. Dos tardes de modelado ahorran tres meses de refactor.

El tipo "Producto"

Cada producto o proyecto documentado es una entidad propia. Eso te permite conectar landing pages comerciales y técnicas sin parchear referencias de texto.

Campos mínimos: nombre, descripción corta, logotipo, estado del ciclo de vida (en desarrollo, GA, mantenimiento, fin de soporte) y referencia a las versiones disponibles. El estado parece accesorio hasta que un cliente te llama porque está integrando un producto que llevas dos años recomendando no usar.

El tipo "Página de documentación"

Aquí va el contenido real. Título, cuerpo con editor enriquecido, producto, versión o versiones aplicables, categoría (instalación, referencia API, troubleshooting, tutorial) y peso numérico para ordenar el índice lateral.

Un detalle del que casi nadie se acuerda al principio y luego se arrepiente: un campo booleano "revisado por ingeniería" y la fecha de última revisión técnica. Dos años después, esos dos campos son la diferencia entre confiar en el contenido o tener que revalidarlo entero.

Versionado: tres caminos y cuándo elegir cada uno

El versionado es donde se complica la conversación. Depende de cuántas versiones mantienes vivas en paralelo y de cómo trabaja tu equipo.

Versionado por taxonomía

El camino corto. Creas un vocabulario "Versiones" con términos v1.0, v2.0, v3.0, y cada página se asocia a una o varias. Filtras con Views y muestras un selector de versión arriba a la derecha, estilo Stripe o Twilio.

Funciona si tu producto evoluciona de forma incremental y la mayoría del contenido se mantiene entre versiones. Cuando un artículo cambia de verdad, lo duplicas y reasignas la taxonomía. La parte fea: duplicar escala mal pasadas cinco o seis versiones activas.

Versionado con Workspaces

Workspaces vive en el núcleo desde Drupal 8.7. Cada workspace representa una versión, los editores trabajan dentro del suyo y publicas todo el bloque cuando la versión sale GA.

Es la opción profesional cuando tienes equipo dedicado y proceso editorial formal. También cuesta explicar al becario que empieza el lunes. Si sois tres personas escribiendo docs entre tarea y tarea, es ametralladora para cazar moscas.

Entity Reference Revisions con Paragraphs

La opción potente: cada sección es un párrafo con historial propio. Puedes cambiar "instalación en Docker" entre la v2 y la v3 sin tocar el resto del artículo, manteniendo historial granular.

Es elegante. También exige modelar bien los paragraphs desde el día uno y formar al equipo editorial. La recomiendo para catálogos de referencia técnica a largo plazo, tipo documentación de un API público con SLA.

En el 70% de los proyectos arrancamos con taxonomía más el módulo Diff, que muestra diferencias entre revisiones. Es lo que mejor equilibrio da entre potencia y curva de aprendizaje. Cómo crear un portal de documentación técnica con versionado y búsqueda facetada usando módulos contribuidos de Drupal no implica irse al esquema más complejo.

La búsqueda: el módulo que decide si la gente vuelve

Si tu buscador no encuentra lo que el usuario necesita en tres segundos, abre Google y busca tu producto más el término. Si Google le sirve mejor que tú, te has quedado fuera de tu propia documentación.

Search API como motor

Search API sustituye al buscador nativo por una arquitectura desacoplada del backend. Decides después si indexas en la base de datos (vale hasta unos miles de páginas), en Apache Solr o Elasticsearch.

Para un portal de docs típico con un par de miles de páginas, Solr es la apuesta segura. Buena calidad en español, comunidad madura, integración limpia con Search API Solr.

Qué indexar y cómo

El índice contiene título, cuerpo, producto, versión, categoría, etiquetas y fecha. El truco está en los procesadores: tokenizer, stemmer en español para que "instalación" e "instalar" devuelvan lo mismo, stopwords adaptadas al dominio (palabras como "documentación" o "Drupal" no aportan señal si aparecen en el 90% de las páginas) y limpieza de HTML para que el código no ensucie con etiquetas sueltas.

Y añade boosting al título y al primer párrafo. Una palabra clave en el H1 vale más que la misma palabra en el cuerpo de un tutorial de 5000 palabras.

Facetas que reflejen cómo piensa el lector

Instala Facets y configura al menos cuatro filtros: producto, versión, categoría y etiquetas. Muestra recuentos junto a cada opción (saber que hay 12 tutoriales de Docker antes de hacer clic ahorra clics frustrados) y aplica AND entre facetas distintas, OR dentro de la misma.

Lo no obvio: la faceta de versión debe actualizarse dinámicamente según el producto seleccionado. Si el usuario filtra por "Producto A" no tiene sentido ofrecerle versiones del B.

Autocompletado para reducir la fricción

Search API Autocomplete sugiere resultados conforme el usuario escribe. Configúralo sobre títulos y los primeros 200 caracteres del cuerpo. El efecto es brutal: las búsquedas con cero resultados caen entre un 40 y un 60% en cuanto lo despliegas.

Navegación: que se sienta como una herramienta seria

Estructura con Book

Book organiza páginas en jerarquías navegables. Cada producto tiene su libro, con capítulos, secciones y navegación anterior/siguiente automática. Es lo más parecido a Read the Docs sin salir de Drupal.

Si te quedas corto, Menu Trail By Path mantiene la migas de pan y la expansión del menú lateral coherentes con la URL.

Tabla de contenidos lateral

TOC API genera el índice a partir de los H2 y H3 de cada página. Sin él, los tutoriales largos se vuelven un scroll infinito frustrante.

Código que se lee

La documentación técnica está plagada de fragmentos de código. CodeFilter o Prism.js / Highlight.js cubren el resaltado. Configura un formato de texto específico con un botón en el editor para insertar bloques por lenguaje. Y mete un botón de copiar al portapapeles: parece tontería, pero los devs que copian con doble clic acaban llevándose espacios o números de línea.

Permisos para mezclar público y privado

Muchos portales mezclan documentación abierta (la que indexa Google) y privada (para clientes con contrato o equipos internos). Drupal lo resuelve sin ayuda externa.

Content Access o Permissions by Term restringen acceso a nivel de nodo o taxonomía. Group crea espacios aislados cuando los clientes solo deben ver sus propias guías. Rabbit Hole redirige a login en lugar de mostrar un feo 403.

Detalle que importa: separa el permiso de ver del de descargar. Que un partner pueda leer una guía no implica que deba poder bajarse el PDF para reenviarlo.

Mantenimiento: el problema real a partir del año dos

El portal lo construyes una vez. La documentación se mantiene siempre.

Crea una vista administrativa con las páginas ordenadas por fecha de última revisión. Marca en rojo lo que pase seis meses sin tocar. Engánchalo a un correo semanal al líder de cada producto: si la lista nunca baja, tienes problema de proceso, no de herramienta.

Content Moderation del núcleo define estados "borrador", "en revisión técnica" y "publicado". Bien implementado evita publicar sin validación técnica, sin convertir cada cambio menor en un calvario burocrático.

Para clientes que insisten en consultar offline, Entity Print genera PDFs decentes de páginas o secciones completas. No es lo principal, pero apaga ciertas conversaciones rápido.

Antes de empezar a instalar módulos

Lo que separa un portal útil de uno abandonado en seis meses casi nunca es la lista de módulos. Es el modelado inicial y el proceso editorial.

Antes de tocar código, contesta tres preguntas: qué versiones vamos a mantener vivas a la vez, quién aprueba los cambios técnicos y cuál es el flujo desde que un developer cambia algo hasta que el cliente lo lee. Si esas respuestas son borrosas, la mejor configuración de Solr no salva el proyecto.

Si te interesa montar un portal que reduzca la carga de soporte y crezca con tu producto, hablemos del alcance y diseñamos juntos la arquitectura.