Rasepi Blog

Los lectores y los escritores están en diferentes modos mentales. ¿Por qué todas las herramientas les ofrecen la misma interfaz de usuario?

2026-04-03T00:00:00Z

Abra Confluence ahora mismo y busque un documento que necesite leer. ¿Qué ve?

Una barra de herramientas. Botones de edición. Cuadros de comentarios. Enlaces al historial de la página. Una barra lateral llena de navegación que no necesita. Migas de pan. Campos de metadatos. Indicadores de permiso. Toda una interfaz de autoría envuelta alrededor del texto que ha venido a leer.

Ahora piense en lo que realmente quería: la respuesta a una pregunta, o los tres pasos siguientes de un proceso, o una política que necesita consultar antes de una reunión dentro de diez minutos.

Usted vino a consumir. La interfaz supuso que usted había venido a crear.

Esto es lo predeterminado en casi todas las plataformas de documentación. Confluence, Notion, SharePoint, GitBook, Nuclino, Slite. Todas ellas presentan el mismo entorno a lectores y escritores. La página es la página. Todo el mundo tiene la misma vista, más o menos unos cuantos botones con permisos.

Parece normal porque nunca hemos tenido otra cosa. Pero es una decisión de diseño, no una ley de la naturaleza. Y es la equivocada.

La misma interfaz para leer y escribir crea una sobrecarga cognitiva](/es/blog/img/readers-writers-ui.svg)

Leer y escribir no son la misma tarea cognitiva

No se trata de una preferencia de interfaz de usuario. Es una diferencia fundamental en el funcionamiento del cerebro.

Cuando escribe, está en modo generativo. Está construyendo, organizando, decidiendo qué incluir y qué omitir. Necesita herramientas: opciones de formato, controles de estructura, incrustación de medios, campos de metadatos, historial de versiones, funciones de colaboración. La interfaz debe proporcionarle potencia y flexibilidad.

Cuando lee, está en modo receptivo. Está escaneando, filtrando, extrayendo lo que es relevante y tratando de seguir adelante. Necesita claridad: tipografía limpia, diseño centrado, distracciones mínimas. La interfaz debe apartarse de su camino.

La psicología cognitiva tiene un marco claro para esto. La Teoría de la carga cognitiva, desarrollada por John Sweller a finales de la década de 1980, distingue entre carga intrínseca (la dificultad del material en sí), carga germana (el esfuerzo de aprender e integrar) y carga extraña (todo lo que el entorno añade que no ayuda). Cada barra de herramientas, barra lateral y botón de edición visible para un lector es carga extraña. No les ayuda a comprender el contenido. Compite activamente por la atención.

Las investigaciones de Mayer y Moreno (2003) sobre el aprendizaje multimedia demostraron que la reducción de los elementos extraños mejora tanto la comprensión como la retención. Su principio de coherencia es directo: la gente aprende mejor cuando se excluye el material extraño en lugar de incluirlo. Una interfaz de documentación que muestre controles de autoría a los lectores está violando este principio en cada carga de página.

El lector no necesita ver las herramientas del escritor. Mostrarlas de todos modos no es neutral. Es activamente perjudicial para la comprensión.

Cómo manejan esto las plataformas actuales (en su mayoría no lo hacen)

Veamos lo que existe.

Confluence tiene un modo de lectura y un modo de edición, pero el modo de lectura sigue rodeado por la navegación, los metadatos y el árbol de páginas de la plataforma. La barra de herramientas de edición desaparece cuando no se está editando, pero el marco mental de "esta es una página wiki editable" nunca desaparece del todo. Todos los lectores ven el botón "Editar". La página susurra: puedes cambiar esto.

Notion es peor en este sentido. Su filosofía central de diseño es que todo es siempre editable. Haga clic en cualquier sitio y estará escribiendo. Eso es brillante para los escritores. Es terrible para los lectores que sólo quieren absorber el contenido sin la ansiedad de modificar algo accidentalmente. La propia [galería de plantillas] de Notion (https://www.notion.com/templates) lo demuestra: cada plantilla es un espacio de trabajo, no una publicación.

SharePoint admite técnicamente distintos diseños de página para la visualización y la edición, pero la experiencia general sigue siendo la de una intranet corporativa. Los lectores se sienten como si estuvieran dentro de una herramienta empresarial, no leyendo un documento optimizado para su comprensión.

GitBook es lo que más se acerca a una experiencia de lectura en primer lugar, con su salida limpia al estilo de la documentación. Pero incluso allí, la experiencia del lector sirve a la suposición de que el lector es un desarrollador mirando documentos técnicos. No está diseñado para el consumidor de conocimientos generales.

Ninguna de estas plataformas trata la lectura como una actividad fundamentalmente diferente de la escritura. La tratan como escribir con la barra de herramientas oculta.

Herramientas actuales: una interfaz, todos los públicos](/es/blog/img/readers-writers-current-tools.svg)

El coste de una interfaz única

No se trata sólo de un problema estético. Tiene consecuencias cuantificables.

La sobrecarga de información reduce la comprensión

Un estudio publicado en el Journal of Consumer Research descubrió que la sobrecarga de información conduce a una peor calidad de la decisión, y que el efecto aumenta a medida que crece la proporción entre información irrelevante y relevante. Una página de documentación con controles de autor visibles, árboles de navegación y campos de metadatos aumenta esa proporción para cada lector que no está allí para escribir.

El cambio de contexto tiene un coste real

Cuando una señal de la interfaz dice "puede editar esto", activa un marco cognitivo diferente al de "lea esto". La investigación de Gloria Mark en la UC Irvine sobre la atención y la multitarea descubrió que se tarda una media de 23 minutos y 15 segundos en volver a centrarse completamente tras un cambio de contexto. Un lector que se plantea momentáneamente editar (aunque sea para corregir una errata) ha sido sacado del modo lectura. No es una hipótesis. Cualquiera que haya utilizado Notion conoce la experiencia de hacer clic para seleccionar texto y empezar a escribir accidentalmente.

Los lectores y los escritores tienen necesidades diferentes ante el mismo contenido

Un escritor necesita ver la estructura, los marcadores de formato, los tipos de bloque, los metadatos y las señales de colaboración. Necesitan toda la maquinaria.

Un lector necesita ver un texto limpio, una jerarquía clara y el camino más rápido hacia la información que busca. Necesitan el contenido, no la maquinaria.

Servir a ambos desde la misma interfaz significa que ninguno obtiene una experiencia optimizada para lo que realmente está haciendo.

Y luego está el tercer público: AI

Aquí es donde la cosa se complica, y donde las plataformas existentes no están en absoluto preparadas.

La documentación en 2026 tiene tres consumidores distintos, no dos:

Escritores que crean y mantienen el contenido
Lectores que consumen contenidos visualmente
Sistemas de inteligencia artificial que recuperan, analizan y sintetizan contenidos mediante programación

Cada uno de estos públicos necesita una interfaz fundamentalmente diferente para el mismo contenido subyacente.

Los escritores necesitan herramientas de edición enriquecidas, funciones de colaboración y controles estructurales. Los lectores necesitan una presentación limpia y centrada con un mínimo de distracciones. La IA necesita una salida estructurada y legible por máquina con metadatos explícitos: señales de frescura, etiquetas de clasificación, direccionamiento a nivel de bloque y un marcado semántico limpio.

Como ya comentamos en Builders, Not Developers, los intermediarios de la IA ya son el consumidor dominante de documentación para una parte cada vez mayor de los trabajadores del conocimiento. La encuesta de desarrolladores 2024 de GitHub descubrió que el 97% de los desarrolladores empresariales han utilizado herramientas de codificación de IA. Para 2026, el 84% de los desarrolladores utilizarán herramientas de IA con regularidad, y el 41% de todo el código será generado por IA.

A estos sistemas de IA no les importa su barra lateral ni su barra de herramientas. Necesitan datos limpios. Y una plataforma que confunde la vista del lector con la del escritor también está confundiendo la superficie consumible por la IA con la superficie de autoría humana. Son tres desajustes en una sola interfaz.

Cómo separa Rasepi las experiencias

Rasepi se basa en el principio de que crear contenidos y consumirlos son actividades distintas que merecen interfaces diferentes.

El entorno del escritor

Cuando escribe en Rasepi, dispone de un entorno de autor completo. Edición de texto enriquecido con TipTap, controles a nivel de bloque, indicadores de estado de traducción, gestión de vencimientos, herramientas de colaboración, vistas de estructura de contenidos y todo lo que un escritor necesita para crear y mantener una documentación de alta calidad.

El redactor ve la maquinaria porque necesita la maquinaria.

El entorno del lector

Cuando alguien consume un documento Rasepi, ve una experiencia de lectura limpia y centrada. Sin cromo de edición. Sin barras de herramientas. Sin señales de "usted podría modificar esto". Sólo el contenido, presentado en un diseño optimizado para la comprensión y el escaneado.

El lector no ve el botón de edición porque no está aquí para editar. Están aquí para aprender algo, seguir un proceso o encontrar una respuesta. La interfaz respeta esa intención.

La superficie AI

Para los consumidores de IA, Rasepi expone el contenido a través de API estructuradas con metadatos completos. Cada bloque lleva su puntuación de frescura, estado de traducción, hash del contenido y etiquetas de clasificación. Los sistemas de IA pueden consultar el contenido a nivel de bloque, filtrar por frescura, excluir el material obsoleto o borrador y recuperar exactamente los datos estructurados que necesitan.

Nada de raspar una página wiki y esperar lo mejor. La IA dispone de una interfaz especialmente diseñada, al igual que el lector y el escritor.

Una capa de contenido, tres interfaces

Lo importante es que no estamos manteniendo tres copias del contenido. Este no es el problema de las cinco copias del mismo documento que comentamos en Deje de mantener cinco copias del mismo documento.

Se trata de una capa de contenido, almacenada como bloques estructurados, servida a través de tres vistas diferentes optimizadas para tres públicos distintos.

El escritor edita bloques. El lector ve el contenido ensamblado y estilizado. La IA consulta datos estructurados con metadatos. Los mismos bloques. La misma fuente de verdad. Diferente capa de presentación para cada consumidor.

Esto sólo es posible gracias a la arquitectura a nivel de bloque. Cada pieza de contenido es una unidad direccionable individualmente con sus propios metadatos. Puede presentar esos bloques de forma diferente en función de quién los solicite:

Audiencia	Necesidades	Obtiene
Escritor	Formateo, estructura, colaboración, metadatos	Entorno de autor completo con controles a nivel de bloque
Lector	Texto limpio, jerarquía clara, escaneo rápido	Vista de lectura centrada, sin cromo de edición
AI	Datos estructurados, puntuaciones de frescura, clasificación	API a nivel de bloque con metadatos completos

Por qué esto importa más de lo que parece

Puede que lea esto y piense: "Es sólo interfaz de usuario. Diferentes vistas de la misma cosa. ¿Qué importancia puede tener?"

Resulta que es muy importante.

Confianza de los lectores

La gente confía en los contenidos que parecen publicados. Cuando una página parece un wiki que cualquiera puede editar, los lectores la descartan inconscientemente. Cuando el mismo contenido se presenta en una vista de lectura limpia y con calidad de publicación, conlleva más autoridad. Esto no es irracional. Es una señal de que alguien se tomó en serio la presentación, lo que implica que también se tomó en serio el contenido.

El Grupo Nielsen Norman ha estudiado este tema en profundidad. Su investigación sobre la credibilidad del contenido muestra que la calidad del diseño y la presentación se encuentran entre las señales más fuertes en las que se basan los usuarios para evaluar la fiabilidad del contenido. Una vista de editor desordenada socava activamente la credibilidad del contenido que muestra.

Productividad del redactor

Los escritores que trabajan en un entorno de autor dedicado no tienen que cambiar de contexto entre "¿estoy leyendo o estoy escribiendo?". Las herramientas están ahí porque se supone que tienen que estar ahí, no porque la interfaz no pueda decidir quién la está mirando.

Fiabilidad de la IA

Cuando los sistemas de IA disponen de una superficie construida a propósito con metadatos estructurados, pueden tomar mejores decisiones sobre qué recuperar y qué excluir. Pueden comprobar las puntuaciones de frescura antes de incluir un bloque en una respuesta. Pueden respetar las etiquetas de clasificación. Pueden filtrar por idioma, estado o audiencia. Nada de eso es posible cuando la IA está raspando la misma página HTML que se diseñó para lectores humanos.

El cambio de modelo mental

El supuesto fundamental de la mayoría de las plataformas de documentación es: la página es la unidad, y todo el mundo interactúa con la página.

La suposición de Rasepi es diferente: el bloque es la unidad, y distintos públicos interactúan con los bloques a través de superficies creadas a tal efecto.

Parece una pequeña distinción arquitectónica. No lo es. Es la diferencia entre una herramienta que accidentalmente muestra contenidos a los sistemas de inteligencia artificial y otra que deliberadamente les sirve. Entre un entorno de escritura que resulta ser legible y una experiencia de lectura diseñada desde cero. Entre una interfaz suficientemente buena y tres excelentes.

La documentación ya no sólo se escribe y se lee. Se escribe, se lee, se consulta, se traduce, se puntúa, se clasifica y se sirve a sistemas de IA a escala. Una única interfaz no puede optimizar todo eso, y fingir que puede es la forma en que acabamos con wikis que nadie quiere leer y asistentes de IA que extraen respuestas de páginas que nunca fueron diseñadas para ser consumidas por máquinas.

Los lectores y los escritores están en modos mentales diferentes. La IA está en un modo completamente diferente. La interfaz debería reflejarlo.

El estado de los documentos en 2026: cinco tendencias que definirán la próxima era

2026-04-03T00:00:00Z

Cada pocos meses dedico una mañana a leer. Ni código Rasepi, ni temas de GitHub. Blogs de la competencia, informes del sector, anuncios de keynote, encuestas a desarrolladores. Cualquier cosa que haya salido en el último trimestre que tenga que ver con la documentación, la gestión del conocimiento o los flujos de trabajo asistidos por IA.

Lo hice la semana pasada y la imagen que surgió fue más nítida de lo que esperaba. No porque un solo anuncio fuera innovador, sino porque convergen cinco tendencias distintas que, al alinearlas, dibujan un panorama muy claro de lo que las plataformas de documentación deberán hacer en los próximos dos años.

Esto es lo que descubrí

1. La IA es ahora el lector principal. No los humanos.

GitBook publicó una cifra sorprendente en su AI docs data report: La lectura de documentación por parte de la IA aumentó más de un 500% en 2025. Quinientos por ciento. Eso no es un error de redondeo.

Mientras tanto, la Encuesta a desarrolladores 2024 de Stack Overflow mostró que el 61% de los desarrolladores pasan más de 30 minutos al día buscando respuestas. Pero la forma en que buscan ha cambiado. La propia encuesta de GitHub descubrió que el 97% de los desarrolladores empresariales han utilizado herramientas de codificación con IA. En 2026, el 84% de los desarrolladores utilizarán herramientas de IA a diario, y el 41% del código estará generado ahora por IA. Estas personas no están navegando por la barra lateral de su wiki. Están preguntando a Claude o Copilot, y la IA está leyendo sus documentos en su nombre.

La implicación es difícil de exagerar. Su consumidor de documentación más frecuente ya no es una persona con una pestaña del navegador abierta. Es un modelo lingüístico haciendo llamadas de recuperación. Y ese modelo no tiene capacidad para entrecerrar los ojos ante una página y pensar "hmm, esto parece anticuado".

GitBook se dio cuenta de esto pronto y respondió con su informe State of Docs 2026 y un impulso hacia los formatos legibles por máquinas. También lanzaron skill.md, una convención para estructurar la información del producto específicamente para agentes de IA. Google fue más allá con su Gemini API Docs MCP, que conecta a los agentes de codificación con la documentación actual a través del Protocolo de Contexto de Modelo. Su razonamiento era explícito: los agentes generan código obsoleto porque sus datos de entrenamiento tienen una fecha límite. La corrección del MCP elevó su tasa de aprobados en la evaluación al 96,3%.

Así que la primera tendencia está asentada. La IA es el lector principal. Las plataformas que traten esto como una restricción central de diseño, no como una característica a añadir más tarde, tendrán una ventaja estructural.

2. La frescura y los metadatos de confianza se están convirtiendo en obligatorios

Anthropic entrevistó a 81.000 usuarios de Claude en diciembre de 2025 y publicó los resultados en marzo de 2026. Se trata del mayor estudio cualitativo de usuarios de IA jamás realizado (159 países, 70 idiomas). ¿La preocupación más citada? La falta de fiabilidad. El 27% de los encuestados la mencionó como su principal preocupación, y el 79% de esas personas la habían experimentado de primera mano.

Esa cifra debería quitar el sueño a todos los equipos de documentación.

Cuando las respuestas de la IA no son fiables, el problema no siempre es el modelo. A menudo, el modelo está reproduciendo fielmente lo que encontró en un documento obsoleto. El modelo no alucinó. Simplemente, sus documentos estaban mal y nadie los señaló.

Los datos de Stack Overflow refuerzan esto desde un ángulo diferente: El 81% de los desarrolladores esperan que la IA esté más integrada en su forma de documentar el código el año que viene. Si el 81% de sus usuarios están alimentando a la IA con documentación, y el 27% de los usuarios de IA dicen que la falta de fiabilidad es el mayor problema, usted tiene un problema de confianza que ninguna cantidad de ingeniería rápida soluciona. La solución está en la fuente.

Por eso importan los metadatos de frescura. No las marcas de tiempo de "última edición" (esas le dicen cuándo alguien tocó el archivo, no si el contenido sigue siendo exacto). Frescura real: estado de las revisiones, salud de los enlaces, alineación de las traducciones, señales de lectura, detección de la deriva del contenido. Metadatos que una máquina pueda leer y utilizar para decidir si es seguro citar un documento.

Sigo volviendo a un simple encuadre. Su documentación necesita una puntuación de crédito. No una marca de tiempo. Una puntuación de crédito. (Hemos estado construyendo exactamente esto con el [sistema de puntuación de frescura] de Rasepi (/características/frescura) y, sinceramente, ver los datos de la industria sólo me hace estar más convencido de que es la decisión correcta).

3. La traducción pasa de "proyecto" a "pipeline".

DeepL publicó en febrero un artículo titulado "The 6 Translation Transformations Global Businesses Can't Afford to Miss". Su argumento: la traducción se está convirtiendo en un reto operativo continuo, no en un proyecto por lotes que se realiza trimestralmente.

Eso concuerda con todo lo que veo.

El antiguo modelo era sencillo. Escriba en inglés. Cuando tenga presupuesto, contrate a un traductor o hágalo pasar por un servicio. Reciba las traducciones. Cárguelas. Hecho hasta la próxima vez. El problema es que "la próxima vez" llega cada vez más rápido cuando su producto se envía semanalmente y sus documentos se actualizan constantemente. Para cuando la versión alemana está de vuelta de la revisión, la fuente inglesa ya ha cambiado dos veces.

El propio [Centro de personalización] de DeepL (https://www.deepl.com/customization-hub) ofrece ahora glosarios, reglas de estilo y ajustes de formalidad, lo cual es estupendo. Pero si esas herramientas viven fuera de su plataforma de documentación, estará gestionando una cadena de herramientas de traducción: editor, exportar, traducir, revisar, reimportar, repetir. Cada paso es una oportunidad para la deriva.

Notion no tiene soporte multilingüe nativo en absoluto. Confluence lo ofrece a través de plugins del mercado. GitBook añadió la traducción automática en agosto de 2025, que es un paso, pero funciona a nivel de página.

El verdadero cambio es del nivel de página al nivel de bloque. Cuando se hace un seguimiento de las traducciones a nivel de párrafo, sólo se retraduce lo que realmente ha cambiado. Una edición típica toca quizá dos párrafos de cuarenta. Eso supone un 94% menos de trabajo de traducción. (Esta es la arquitectura central de traducción de Rasepi y, sinceramente, de lo que más orgulloso estoy del producto. Pero incluso dejándonos de lado, la dirección de la industria es clara: la traducción continua, incremental e integrada es hacia donde se dirige esto).

4. Los agentes de IA necesitan contenidos estructurados, no páginas wiki

Ésta cristalizó para mí cuando Notion anunció Custom Agents en febrero. 21.000 agentes construidos durante el acceso anticipado. Agentes que responden a preguntas de las bases de conocimientos, enrutan tareas, compilan informes de estado. Sólo la rampa tiene más de 300 agentes.

Atlassian fue en una dirección similar. Rovo AI in Confluence extrae el contexto de todas las aplicaciones de Atlassian y de terceros para generar contenido. Su discurso: "contenido rico en contexto y de alta calidad basado en el trabajo existente de su equipo".

Y luego Anthropic lanzó equipos de agentes en Claude Code, donde múltiples agentes de IA se coordinan de forma autónoma en tareas complejas. Opus 4.6 obtiene una puntuación del 76% en la prueba de 8 agujas 1M MRCR (frente al 18,5% del modelo anterior), lo que significa que realmente puede recuperar información enterrada en lo más profundo de conjuntos masivos de documentos sin perder el rastro.

Las tres empresas están construyendo agentes que consumen documentación. Ninguna de ellas ha resuelto el problema de la calidad de la fuente.

La documentación de los agentes personalizados de Notion reconoce explícitamente el riesgo de inyección rápida cuando los agentes leen contenido que no es de confianza. Rovo de Atlassian coge todo lo que encuentra en su Confluence. Si ese contenido tiene tres meses de antigüedad, Rovo no lo sabe. Construye sobre él de todos modos.

Para que los agentes funcionen de forma fiable, necesitan algo más que páginas de texto. Necesitan contenidos estructurados con identificadores estables, señales explícitas de frescura, metadatos de clasificación claros y la capacidad de distinguir "esto es actual y está revisado" de "esto existe pero nadie lo ha tocado en un año". Las páginas wiki no proporcionan eso. El contenido estructurado a nivel de bloque con metadatos de confianza sí lo hace.

5. El código abierto y el autoalojamiento están resurgiendo

Esto último es más una corazonada respaldada por datos que un simple anuncio.

GitBook open-sourced their published documentation a finales de 2024 y lanzó un fondo OSS. Su razonamiento: los proyectos de código abierto merecen herramientas de documentación gratuitas y de alta calidad. Pero el movimiento también señala algo más amplio.

Notion es sólo en la nube. No hay opción de autoalojamiento. Confluence Data Center existe pero requiere una licencia. Cuando su plataforma de documentación alberga sus conocimientos operativos más sensibles (libros de jugadas de incidentes, procedimientos de cumplimiento, decisiones de arquitectura), la pregunta de "¿quién controla estos datos?" no es abstracta.

El post de Anthropic "Claude es un espacio para pensar" de febrero planteaba un argumento interesante sobre la confianza y los modelos de negocio. Su afirmación central: los incentivos publicitarios son incompatibles con un asistente de IA realmente útil. Optaron por mantenerse sin publicidad para que los usuarios confíen en la herramienta.

Creo que existe un paralelismo para las plataformas de documentación. Si su sistema de documentación es de código cerrado y sólo en la nube, no puede verificar lo que alimenta a la IA. No puede auditar los cálculos de frescura. No puede asegurarse de que sus datos permanezcan bajo su control. Para los equipos que están desplegando asistentes de IA en la parte superior de su base de conocimientos (y cada vez más, todo el mundo está haciendo esto), la auditabilidad importa.

No se trata de una polémica sobre si el código abierto es moralmente superior. Los productos de código cerrado pueden ser absolutamente dignos de confianza. Pero cuando está construyendo flujos de trabajo impulsados por IA sobre su documentación interna, la capacidad de inspeccionar y verificar el sistema es una ventaja práctica. Para nosotros, la licencia MIT de Rasepi no fue una idea de última hora. Fue una decisión de diseño arraigada en la misma lógica: la infraestructura de documentación debe ser auditable.

Lo que significan estas cinco tendencias juntas

Individualmente, cada una de estas tendencias es manejable. ¿La IA lee sus documentos? Bien, añada metadatos legibles por máquina. ¿La frescura importa? Bien, añada fechas de revisión. ¿La traducción debe ser continua? Claro, integre DeepL. ¿Los agentes necesitan estructura? Justo, mejore su modelo de contenidos. ¿La soberanía importa? Estupendo, ofrezca una opción de autoalojamiento.

Pero tomados en conjunto, describen una plataforma que parece fundamentalmente diferente de lo que la mayoría de los equipos utilizan hoy en día.

La brecha es arquitectónica. No se trata de cinco características que se puedan añadir. Son cinco supuestos que deben incorporarse a los cimientos. Cómo se almacena el contenido (a nivel de bloque, no de página). Cómo se modela la confianza (puntuaciones de frescura, no marcas de tiempo). Cómo funciona la traducción (incremental, incrustada, por párrafo). Cómo acceden los agentes de IA a los contenidos (API estructuradas con metadatos, no raspado de páginas). Cómo se controlan los datos (abiertos, auditables, autoalojables).

Ninguna plataforma establecida se ha diseñado en torno a estos cinco aspectos simultáneamente. Algunas las están añadiendo poco a poco. GitBook se está moviendo más rápido en el frente de la legibilidad de la IA. Notion está construyendo una infraestructura de agentes. Atlassian tiene distribución empresarial.

¿Pero diseñar para los cinco desde el primer día? Esa es la ventaja de empezar de cero cuando el terreno se mueve.

Soy consciente de que aquí soy parcial. Construimos Rasepi específicamente porque vimos que estas tendencias convergían y queríamos una plataforma que las asumiera todas desde el principio. Traducción a nivel de bloque, caducidad forzosa, puntuación de frescura, contenidos estructurados listos para la IA, código abierto. Es la tesis de todo el proyecto.

Pero aunque no existiéramos, creo que cualquier lectura honesta de lo ocurrido en el primer trimestre de 2026 apunta en la misma dirección. La documentación se está convirtiendo en infraestructura. Y la infraestructura tiene requisitos diferentes a los de las páginas wiki.

Los equipos que descubran esto primero no sólo tendrán mejores documentos. Tendrán agentes de IA más fiables, menores costes de traducción, menos sorpresas de cumplimiento y bases de conocimientos que realmente sigan siendo fiables con el paso del tiempo.

Ese será el estado de los documentos en 2026. La cuestión no es si estas tendencias son reales. Es si su plataforma ha sido diseñada para ellas.

Cinco tendencias. Una pregunta arquitectónica: ¿su plataforma de documentación se diseñó para 2026 o sigue sirviendo supuestos de 2016?

Fuentes: GitBook AI docs data report, GitBook State of Docs 2026, GitBook skill.md, Google Gemini API Docs MCP, Stack Overflow 2024 Developer Survey, GitHub 2024 developer survey, Index.dev developer productivity statistics, Anthropic "What 81,000 People Want from AI", Anthropic "Claude es un espacio para pensar", Claude Opus 4.6, Agentes personalizados de Notion, Atlassian Rovo en Confluence, DeepL "6 transformaciones de traducción", DeepL Customization Hub, Documentación de código abierto de GitBook, Traducción automática de GitBook.

Constructores, no desarrolladores: Cómo Claude cambió para quién son sus documentos

2026-04-02T00:00:00Z

Hay una persona ahora mismo, en algún lugar, integrando su API. No están en su sitio de documentación. No han abierto su guía de inicio. No han visto su zona de juegos interactiva ni su cuidada barra lateral de navegación.

Están sentados en Claude. O Copiloto. O Cursor. Han tecleado algo como "integrar la API de facturación de Stripe con mi aplicación Next.js utilizando el enrutador de aplicaciones" y han esperado a que les devolviera el código funcional. La IA leyó sus documentos en su nombre. Encontró los puntos finales relevantes, entendió el flujo de autenticación, eligió los métodos SDK correctos y produjo una implementación.

Hace dos semanas, en el Start Summit Hackathon de St. Gallen, vi cómo ocurría esto en tiempo real. Estaba hablando con un grupo de estudiantes de CS y un par de fundadores de startups en fase inicial sobre cómo abordan las nuevas API, y todos y cada uno de ellos describieron el mismo flujo de trabajo: pegar el problema en una IA, obtener código de vuelta, iterar a partir de ahí. Una de las estudiantes se rió cuando le pregunté si había leído los documentos. "¿Por qué iba a hacerlo? Claude los lee por mí".

La persona nunca visitó su sitio. Puede que nunca visiten su sitio. Y así es como se construye cada vez más el software.

El cambio fundamental

La documentación tiene ahora dos consumidores fundamentalmente diferentes: los humanos que la leen y los asistentes de IA que la leen en nombre de los constructores. La mayor parte de la documentación está optimizada exclusivamente para los humanos. La IA es ya el lector dominante.

Esto lo cambia todo aguas abajo:

La frescura es ahora un problema de fiabilidad. Cuando una IA sirve contenido rancio, el constructor no tiene forma de detectar el problema. El daño escala silenciosamente.
"Desarrollador" es una palabra demasiado estrecha. Los jefes de producto, diseñadores y analistas están distribuyendo software a través de asistentes de IA, a menudo sin haber leído ellos mismos ni una línea de documentación.
Una estructura legible por la máquina es más importante que el diseño visual.** Un markdown limpio, bloques autocontenidos y metadatos explícitos son lo que permite a la IA representar su producto con precisión.
Los requisitos de formato se han dividido. Los lectores humanos necesitan narrativa. Los intermediarios de la IA necesitan especificaciones estructuradas y parseables. Usted necesita servir a ambos.

El resto de este artículo explica cómo hemos llegado hasta aquí, qué significa esto para DevRel y qué puede hacer al respecto ahora mismo.

El viaje que nadie planeó

Durante mucho tiempo, las relaciones con los desarrolladores siguieron un camino bien entendido. Usted redactó una documentación exhaustiva. Publicó guías de inicio rápido. Usted dio charlas en conferencias. Usted mantuvo una presencia en Stack Overflow. Usted hizo que la referencia de su API fuera buscable, sus SDK idiomáticos, sus mensajes de error útiles.

Ese camino suponía que el desarrollador leería su contenido. Navegaría por tu estructura. Seguiría sus pasos.

La encuesta de desarrolladores 2024 de GitHub reveló que el 97% de los desarrolladores empresariales han utilizado herramientas de codificación de IA en algún momento. La encuesta anual de Stack Overflow mostró que el 76% de todos los desarrolladores utilizan o tienen previsto utilizar herramientas de IA, y que el 62% de los profesionales las utilizan activamente en su día a día. Para 2026, esa cifra subía al 84%, con el 41% de todo el código generado ahora por IA y el 51% de los desarrolladores profesionales utilizando herramientas de IA a diario. Esas cifras no se están ralentizando.

El nuevo viaje tiene un aspecto diferente. Alguien describe lo que quiere en lenguaje natural. Un asistente de IA lee la documentación, encuentra las secciones relevantes y genera la integración. El constructor revisa el resultado, tal vez refina la solicitud, tal vez pide un seguimiento. Minutos, no horas.

¿El embudo de puesta en marcha que los equipos de DevRel pasaron años perfeccionando? Se está obviando. No porque fuera malo. Simplemente, el punto de entrada se ha desplazado.

Dos consumidores, un conjunto de documentos

La documentación tiene ahora dos públicos fundamentalmente diferentes.

El primero es el lector humano. Esta persona sigue existiendo. Aparecen para tomar decisiones de arquitectura, depurar casos límite, revisar la conformidad y comprender conceptos. Quieren explicaciones narrativas, material de referencia bien organizado y un razonamiento claro sobre las compensaciones.

El segundo es el intermediario de la IA. Lee su documentación en nombre de un constructor. No le importa su barra lateral. No aprecia su diseño visual. Necesita un contenido estructurado y comprensible para la máquina: un markdown limpio, un formato coherente, especificaciones explícitas sobre las que pueda razonar sin ambigüedades.

Hoy en día, casi todos los sitios de documentación están optimizados exclusivamente para el primer público. El segundo público es ya el consumidor dominante.

Jeremy Howard identificó esta tensión cuando propuso la norma /llms.txt en 2024. Su observación fue precisa: "Los grandes modelos lingüísticos dependen cada vez más de la información de los sitios web, pero se enfrentan a una limitación crítica: las ventanas de contexto son demasiado pequeñas para manejar la mayoría de los sitios web en su totalidad." La propuesta es sencilla. Un archivo markdown curado en /llms.txt que proporcione a los modelos de IA una visión general estructurada de su producto y enlaces a los recursos más importantes. FastHTML, los propios documentos de Anthropic y un directorio creciente de proyectos ya incluyen uno.

Es una convención útil. Pero también es un síntoma de un problema más profundo. El verdadero problema no es el formato. Es que la mayor parte de la documentación nunca se diseñó pensando en el consumo por parte de las máquinas.

El constructor no recorta gastos

Existe la tentación de mirar a la persona que pregunta a Claude en lugar de leer la documentación y concluir que está tomando atajos. Que no entienden realmente lo que ocurre en el código. Que de alguna manera son un tipo de desarrollador inferior.

Ya he tenido esta conversación suficientes veces como para saber que eso suele ser erróneo.

Muchos de estos constructores son ingenieros experimentados que toman decisiones deliberadas sobre la eficiencia. Entienden el código, simplemente no quieren navegar por cuatro páginas de documentación para encontrar las tres líneas que realmente necesitan. Han aprendido que un asistente de IA puede extraer esas líneas más rápido de lo que ellos pueden escanearlas, así que delegan la lectura. (Sinceramente, yo mismo hago esto. No recuerdo la última vez que leí una guía de inicio de arriba abajo).

Anthropic reconoció este patrón cuando construyó el Protocolo de Contexto Modelo. El MCP está ahora soportado por Claude, ChatGPT, VS Code, Cursor y otros. Está diseñado explícitamente para que los asistentes de IA puedan llegar a sistemas externos, extraer contexto y actuar en consecuencia. La especificación lo describe como un "acceso a un ecosistema de fuentes de datos, herramientas y aplicaciones que aumentarán las capacidades y mejorarán la experiencia del usuario final".

Léalo con atención. Es lenguaje de infraestructura, no de conveniencia. Los constructores que utilizan estas herramientas no están evitando el trabajo. Están trabajando a través de una nueva capa, y su documentación forma parte de esa capa, tanto si usted la diseñó para ello como si no.

Las cifras respaldan esto. Sólo Claude gestiona en la actualidad 25.000 millones de llamadas API al mes, con 30 millones de usuarios activos mensuales en 159 países. El 70% de las empresas de la lista Fortune 100 utilizan Claude. Según un estudio de Menlo Ventures, Anthropic posee el 32% de la cuota de mercado de la IA empresarial por uso de modelos, por delante de OpenAI con un 25%. Un informe de investigación de HSBC lo sitúa incluso por encima: 40% por gasto total en IA. No se trata de herramientas experimentales. Son infraestructuras primarias.

Las relaciones con los desarrolladores se construyeron para otra época

Si su estrategia DevRel se diseñó antes de 2023, se diseñó para un mundo en el que los desarrolladores leían los documentos directamente. Ese mundo no ha desaparecido, pero ya no es el patrón de interacción dominante para una parte cada vez mayor de los desarrolladores.

Esto cambia el cálculo de varias actividades de DevRel de larga data.

Conferencias. Una presentación de 45 minutos en una conferencia de desarrolladores llega a una sala de unos cientos de personas. Un archivo /llms.txt bien estructurado y una documentación limpia y legible por máquina llegan a todos los constructores que preguntan a cualquier asistente de IA sobre su producto, continuamente, en cualquier momento. La charla es un acontecimiento único. La documentación legible por máquina se acumula. No digo que las conferencias no valgan nada (literalmente acabo de volver de una), pero la ecuación de apalancamiento ha cambiado.

Guías de inicio. El clásico tutorial de inicio rápido en cinco pasos es cada vez más una formalidad. El constructor no sigue pasos. Describen lo que quieren y esperan que la IA produzca la integración. Si la API está bien documentada en un formato apto para las máquinas, la IA se encarga de la experiencia de puesta en marcha de forma más eficiente de lo que podría hacerlo cualquier tutorial. En su lugar, los tutoriales deberían convertirse en material conceptual: explicar por qué elegir el enfoque A en lugar del B. La IA puede generar la implementación. Es mucho menos fiable a la hora de explicar las compensaciones.

Stack Overflow. Los datos de su propia encuesta muestran que el 84% de los desarrolladores utilizan la documentación técnica directamente, y el 90% de ellos confían en la documentación de los paquetes de API y SDK. Pero la forma en que acceden a esos documentos es cada vez más a través de una capa de IA, no de una pestaña del navegador. Las preguntas que todavía llegan a Stack Overflow tienden a ser las difíciles. Casos límite, depuración de producción, cosas que requieren matices. Valiosas, seguro. Pero ya no es donde está el volumen.

Cuando la IA lee sus documentos, la frescura se vuelve crítica

Esta es la parte en la que la mayoría de los equipos no han pensado.

Cuando un humano lee una página de documentación, puede aplicar su juicio. Pueden notar que las capturas de pantalla parecen antiguas, o que un comentario al final dice que el proceso ha cambiado. Pueden entrecerrar los ojos y pensar "esto parece anticuado".

Un asistente de IA no puede hacer nada de eso. Lee el texto, lo procesa como un hecho y genera una respuesta con total confianza. Si la documentación describe un punto final obsoleto, la IA recomendará alegremente integrarse con él. Si la documentación hace referencia a una infraestructura que fue sustituida hace seis meses, la IA describirá la antigua configuración como actual. Sin titubeos.

Y aquí está lo que hace que esto sea peor de lo que parece: El 66% de los desarrolladores ya dicen que el mayor problema con las herramientas de IA es que dan resultados que son "casi correctos pero no del todo". La documentación obsoleta alimenta directamente ese problema. La IA no está alucinando. Está reproduciendo fielmente contenido obsoleto, y no hay forma de que el constructor note la diferencia.

El constructor confía en la IA. La IA confía en la documentación. Si la documentación está anticuada, esa cadena de confianza ofrece una respuesta errónea con toda seguridad.

Esto siempre ha sido un problema, obviamente. El contenido obsoleto siempre ha confundido a la gente. Pero el daño se contenía porque los lectores humanos a veces podían detectarlo. Los intermediarios de la IA no pueden. Amplifican el contenido rancio sirviéndolo a escala, con autoridad, a personas que no tienen motivos para dudar de él.

La frescura ya no es una cuestión de calidad del contenido. Es una cuestión de fiabilidad para cada flujo de trabajo impulsado por IA que toque sus documentos.

La palabra "desarrollador" es demasiado estrecha

Las personas que construyan software en 2026 no se identificarán todas como desarrolladores. Algunos son diseñadores que incitan a Claude a construir un prototipo funcional. Algunos son jefes de producto que utilizan Cursor para enviar herramientas internas. Algunos son analistas de datos que describen una canalización de datos en lenguaje natural y dejan que un agente la ensamble. En la Cumbre Start, la mitad de los equipos del hackathon contaban con miembros sin conocimientos de programación que, al final del fin de semana, ya estaban distribuyendo software operativo.

Ramp es un ejemplo útil. Esta empresa de tecnología financiera pasó de una valoración de 5.800 millones de dólares en 2023 a 32.000 millones de dólares a finales de 2025, superando los 1.000 millones de dólares de ingresos anualizados por el camino. Es una de las startups de más rápido crecimiento de la historia. Una parte muy discutida de su enfoque: los jefes de producto construyen características directamente con herramientas de IA en lugar de esperar en un backlog de ingeniería. Los PM de Ramp no se limitan a escribir especificaciones. Envían código. La IA se encarga de la implementación. El PM se encarga de la intención.

No es un atajo. Un nuevo modelo operativo, y está funcionando a una escala que hace muy difícil descartarlo como experimento.

El propio estudio interno de Anthropic es revelador aquí. Cuando encuestaron a 132 de sus propios ingenieros sobre cómo utilizan Claude, los ingenieros informaron de que lo utilizaban para cerca del 60% de sus tareas laborales. ¿Los usos más comunes? Depurar el código existente, comprender qué hacían algunas partes de la base de código e implementar nuevas funciones. Los ingenieros dijeron que tienden a entregar a Claude tareas "no complejas, repetitivas, en las que la calidad del código no es crítica". Y el 27% del trabajo que hacen ahora con Claude simplemente no lo habrían hecho antes.

Es el propio equipo de Anthropic. Las personas que construyeron el modelo lo están utilizando como lector de documentación, navegador de base de código y generador de primeros borradores. Todos los demás están haciendo lo mismo, sólo que con su documentación en lugar de la de ellos.

Anthropic ha sido deliberado a la hora de llamar a este personaje "constructor". Sus herramientas están diseñadas no sólo para ingenieros de software profesionales, sino para cualquiera que pueda describir lo que quiere construir. Cuando Claude puede crear una aplicación completa a partir de un diseño Figma mediante MCP, la línea tradicional entre "desarrollador" y "no desarrollador" se disuelve.

Esto tiene implicaciones reales para cualquiera que mantenga documentación o se preocupe por la experiencia de los desarrolladores. Su público ya no se limita a las personas que saben lo que es un punto final REST. Incluye a cualquiera cuyo asistente de IA pueda interactuar con su producto. ¿El PM de Ramp que lanza una función utilizando su API? Probablemente nunca lea directamente su documentación. Su agente de IA sí que lo hará.

Lo que esto significa para la documentación

Si la documentación sirve ahora a dos públicos, los lectores humanos y los intermediarios de la IA, tiene que funcionar para ambos. Suena obvio. En la práctica, casi nadie lo hace.

Esto es lo que creo que realmente importa:

**Si la documentación de su API es una bonita página HTML que un LLM tiene que raspar y analizar, la IA está trabajando más de lo que debería. Envíe la especificación OpenAPI sin procesar junto con la versión renderizada. Envíe un markdown limpio. Haga que las especificaciones sean accesibles sin necesidad de que la IA interprete el diseño de la página.

Estructura a nivel de bloque en lugar de narrativa a nivel de página. Los asistentes de IA no consumen la documentación página por página. Extraen las secciones relevantes. Un documento con encabezados claros, párrafos autocontenidos y una semántica explícita a nivel de bloque es mucho más útil para una IA que una narración fluida que requiera leer toda la página para conocer el contexto.

Confíe en las señales de que las máquinas saben leer. ¿Cuándo se revisó este documento por última vez? ¿Sigue siendo actual? ¿Se ha marcado el contenido? Estas señales deben existir de forma que la IA pueda acceder a ellas, no sólo como señales visuales en una página web. Una puntuación de frescura, un estado de caducidad, una fecha de revisión, estos son los metadatos que permiten a una IA decidir si un documento es seguro para utilizarlo como fuente.

La frescura como prerrequisito, no como característica. Cuando un asistente de IA sirve a un constructor una respuesta segura basada en un punto final obsoleto, el daño es peor que un 404. El constructor construye sobre él. El constructor construye sobre ella. Lo lanza al mercado. Luego se rompe en producción, y nadie sabe por qué hasta que alguien lo rastrea hasta la documentación que debería haber sido actualizada hace meses. Cada documento al que una IA pueda hacer referencia necesita un mecanismo que demuestre que sigue siendo actual. (Este es, con toda sinceridad, exactamente el problema que estamos construyendo Rasepi para resolver. Forzar la caducidad de los bloques de documentación para que el contenido obsoleto no pueda esconderse).

Para empezar: audite su documentación actual

Si ha leído hasta aquí y está pensando "vale, pero ¿qué hago realmente el lunes?", aquí tiene cuatro cosas concretas que puede comprobar esta semana.

1. Pruebe sus documentos a través de una IA. Abra Claude o ChatGPT y pídale que integre su producto en un escenario realista. No utilice sus conocimientos internos. Fíjese sólo en lo que produce la IA. ¿Es correcto? ¿Es actual? ¿Está utilizando los puntos finales correctos, la versión correcta del SDK, el flujo de autenticación correcto? Si la IA se equivoca, eso es lo que los constructores están obteniendo en este momento.

**2. Elija las cinco páginas de documentación más visitadas y pregúntese: ¿cuándo se revisó por última vez? ¿Sigue describiendo el estado actual del producto? Si no puede responder con seguridad, tampoco podrá hacerlo una IA. Esta es la única solución de alto rendimiento para la mayoría de los equipos.

**3. Si no tiene un archivo /llms.txt, cree uno. Si su referencia API sólo está disponible como HTML renderizado, exporte la especificación OpenAPI sin procesar y hágala accesible. Si sus documentos están en un CMS que no produce un markdown limpio, ese es un problema que vale la pena resolver ahora.

4. Añada fechas de revisión y metadatos de frescura. Incluso algo sencillo, un campo last-reviewed en su sistema de gestión de contenidos, un ciclo de revisión obligatorio para las páginas de alto tráfico. Esto da tanto a los humanos como a la IA una señal sobre si el contenido es digno de confianza. Herramientas como Rasepi pueden automatizar esto con la caducidad forzosa a nivel de bloque, pero incluso un proceso manual es mejor que nada.

El cambio silencioso en la representación de los productos

Hay una consecuencia más amplia de todo esto que merece la pena exponer directamente.

Su documentación ya no es sólo un manual de referencia para desarrolladores. Es el material de partida que los asistentes de IA utilizan para representar su producto ante el mundo. Cuando un constructor pregunta a Claude cómo utilizar su producto, la respuesta de Claude está moldeada por lo que pueda encontrar y analizar de su documentación.

Buena documentación, buena respuesta. ¿Anticuados, ambiguos, encerrados en HTML difícil de analizar para un modelo? Peor respuesta, o una respuesta incorrecta. Así de sencillo.

La calidad de la respuesta de la IA sobre su producto es ahora un indicador directo de su experiencia como desarrollador. La mayoría de las empresas aún no lo tratan así.

Los equipos que van por delante en esto, Stripe, Vercel, Cloudflare, el propio Anthropic, tratan la legibilidad de la IA como una preocupación de primera clase. Un requisito fundamental que da forma a cómo se escribe, estructura y mantiene la documentación. No es un tema pendiente para el próximo trimestre.

El constructor que está sentado en Claude ahora mismo, describiendo lo que quiere construir, espera un código que funcione en cuestión de minutos. Puede que nunca vuelvan a visitar un sitio de documentación. Pero la IA que les atiende sí lo hará. Constantemente.

Esa IA es ahora su lector más frecuente. La cuestión es si su documentación está preparada para ello.

La mejor estrategia de experiencia del desarrollador en 2026 no es una charla en una conferencia o una guía rápida. Es asegurarse de que la IA lo hace bien.

Este post hace referencia a investigaciones y documentación de productos disponibles públicamente. Las estadísticas se han extraído de GitHub's 2024 developer survey, la Stack Overflow 2024 Developer Survey, Index.dev's 2026 developer productivity report, Incremys Claude statistics, y Fortune's reporting on Anthropic. La especificación /llms.txt se mantiene en llmstxt.org. El protocolo de contexto de modelo está documentado en modelcontextprotocol.io.

Cómo funcionan realmente las traducciones de Rasepi y por qué suenan como su equipo

2026-03-31T00:00:00Z

Si alguna vez ha pasado un documento por Google Translate, o honestamente por cualquier herramienta de traducción, ya conoce el resultado. Técnicamente correcto. Tonalmente incorrecto. Su producto se llama de repente de otra manera. La taquigrafía interna de su equipo desaparece. Un "usted" formal donde su empresa utiliza el informal, o al revés.

El resultado se traduce, pero no suena a usted.

Para eso construí el sistema de traducción de Rasepi. No "podemos traducir la documentación" (todas las herramientas pueden hacerlo ahora) sino "podemos traducirla para que suene realmente como la escribió nuestro equipo".

La respuesta es sí. Y no requiere un equipo de traductores profesionales para conseguirlo.

Traducciones que suenan como su equipo](/es/blog/img/natural-translations.svg)

Sólo se traduce lo que ha cambiado

La mayoría de las plataformas de documentación traducen páginas enteras. Usted cambia una frase y todo el documento se va a retraducir. Cada idioma, cada párrafo, haya cambiado o no.

Rasepi funciona de forma diferente. Hace un seguimiento individual de cada párrafo. Cuando edita una sección de un documento de 20 secciones, sólo esa sección se retraduce. Las otras 19, en todos los idiomas, permanecen exactamente como estaban.

Esto significa dos cosas:

Sus costes de traducción se reducen drásticamente. Hablamos de un 94% menos para las ediciones típicas. La mayoría de las actualizaciones tocan una o dos secciones, no toda la página.
**Si su equipo alemán aprobó una traducción la semana pasada, la edición de un párrafo no relacionado en inglés no afectará al texto aprobado.

El sistema sabe lo que ha cambiado porque cada párrafo tiene una identidad única y una huella digital de contenido. Cuando la huella digital cambia, ese párrafo específico se marca para su retraducción. Nada más.

Su glosario, su terminología

Aquí es donde la cosa se pone interesante.

Cada empresa tiene su propio vocabulario. "Sprint Review" podría quedarse como "Sprint Review" en sus documentos en alemán porque su equipo de Berlín utiliza el término en inglés. O puede convertirse en "Sprint-Überprüfung" porque su equipo de Múnich prefiere la versión alemana. "Base de conocimientos" podría ser "Wissensdatenbank" o "Base de conocimientos" o algo totalmente diferente que su equipo haya acuñado internamente.

Rasepi le permite crear un glosario para cada idioma. Básicamente, una lista de términos y sus traducciones aprobadas. Cuando se traduce un párrafo, el sistema comprueba primero su glosario. Cada término de su lista se traduce exactamente como usted lo definió. Cada vez. En todos los documentos.

Puede gestionar su glosario directamente en Rasepi:

Añadir términos uno a uno a medida que observe incoherencias.
Importe un CSV si ya tiene una lista terminológica de otro sistema
Exporte su glosario para compartirlo con traductores externos u otras herramientas

El glosario funciona por pares de idiomas. Su glosario inglés-alemán está separado de su glosario inglés-francés. Esto es importante porque el mismo término inglés puede necesitar un tratamiento diferente en las distintas lenguas. "Sprint Review" podría seguir siendo inglés en alemán pero traducirse en japonés.

Cuando actualice su glosario, el cambio surtirá efecto la próxima vez que se traduzca cualquier párrafo a ese idioma. No es necesario volver a traducirlo todo manualmente. El siguiente ciclo de edición natural lo recoge.

Reglas de estilo: hacer que las traducciones suenen como si las hubiera escrito usted

Los glosarios se ocupan de las palabras sueltas. Pero una traducción puede utilizar todos los términos correctos y aun así parecer fuera de lugar. Tono incorrecto. Fechas con el formato equivocado. Números con el separador equivocado. Símbolos de moneda en el lugar equivocado.

Para eso están las normas de estilo.

Para cada idioma, puede establecer un conjunto de reglas que controlen la forma de las traducciones:

Convenciones de formato

Son los detalles que hacen que un documento parezca nativo y no "obviamente traducido del inglés":

Formatos de fecha y hora. Reloj de 24 horas para el alemán, AM/PM para el inglés, etc.
Formatos numéricos. La coma como separador decimal en alemán (3,14 en lugar de 3,14), punto para los miles
Reglas de puntuación. Formato de grados académicos, estilos de comillas y otras convenciones regionales

Usted elige las convenciones que se ajustan a las normas de su empresa. Rasepi las aplica a todas las traducciones en ese idioma, en todos los documentos.

Instrucciones personalizadas

Aquí es donde las cosas se ponen realmente potentes. Las instrucciones personalizadas son directivas en lenguaje llano que indican al motor de traducción cómo manejar su contenido. Usted las escribe en frases normales y el motor las sigue.

Algunos ejemplos:

"Utilice un tono amable y diplomático " para una empresa que desea una documentación accesible
"Utilice siempre la forma formal 'Sie', nunca 'du'" para una comunicación profesional en alemán
"Utilice la ortografía del inglés británico: color, organización, licencia " cuando su público anglófono resida en el Reino Unido
"Ponga símbolos de moneda después de la cantidad numérica " para ajustarse a las convenciones europeas
"Cuando describa los puntos finales de la API, utilice el modo imperativo " para documentos técnicos que deben parecer directos

Puede añadir hasta 200 instrucciones personalizadas por idioma. Funcionan junto con su glosario y reglas de formato, y el motor de traducción las tiene en cuenta todas juntas en cada traducción.

Formalidad

El alemán tiene "du" y "Sie". El francés tiene "tu" y "vous". El japonés tiene múltiples niveles de cortesía. Incluso las lenguas sin pronombres formales/informales obvios tienen diferencias tonales que importan.

Rasepi le permite configurar el nivel de formalidad de cada idioma. Una vez configurado, cada párrafo traducido se ajusta a ese tono. Si su empresa se dirige a los lectores de manera formal en francés ("vous") pero informal en alemán ("du"), eso es exactamente lo que hará cada traducción.

Todo funciona a la perfección

Esto es lo que importa: los términos del glosario, las convenciones de formato, las instrucciones personalizadas y los ajustes de formalidad se aplican a todas las traducciones a la vez. Usted no elige uno u otro. Los configura todos una vez, y cada párrafo que se traduce pasa por el mismo conjunto de reglas.

El resultado son traducciones que se leen como si alguien de su equipo local las hubiera escrito. No como si una máquina hubiera traducido cada frase sin saber nada de su empresa.

Cada idioma puede tener su propio contenido

Esta es la característica que más sorprende a la gente.

En Rasepi, un documento traducido no es una copia cerrada del original. Cada versión lingüística puede tener contenido que sólo existe en ese idioma.

¿Por qué es esto importante?

Porque los distintos mercados necesitan cosas diferentes:

Su documentación alemana podría necesitar una sección de cumplimiento de DSGVO (GDPR) que no se aplica a la versión de EE.UU.
Su equipo japonés podría necesitar una nota sobre las herramientas locales que nadie más utiliza
Su oficina brasileña podría necesitar contexto sobre la normativa fiscal regional

En la mayoría de las herramientas de traducción, añadir contenido a una versión lingüística significa que se sobrescribe la próxima vez que alguien vuelva a traducir del inglés. Los equipos se dan cuenta rápidamente y dejan de añadir contenido local. Crean documentos sombra en Notion o Slack o en cualquier otro lugar, y ahora usted tiene dos sistemas en los que nadie confía plenamente.

En Rasepi, el contenido único se marca como perteneciente a ese idioma. Nunca se sobrescribe por una retraducción. Nunca se borra cuando cambia la fuente en inglés. Vive junto al contenido traducido como parte natural del documento.

Lo mismo ocurre con la estructura. Si sus traductores japoneses prefieren listas numeradas donde la versión inglesa utiliza viñetas (una convención común en la escritura técnica japonesa), pueden cambiar el formato. Rasepi conserva esa elección en futuras actualizaciones.

Cada versión lingüística es un documento de primera clase, no una réplica de sólo lectura.

Automático y humano: trabajan juntos

Rasepi no le obliga a elegir entre traducción automática y traducción humana. Admite ambas, y conoce la diferencia.

Cuando un párrafo se traduce automáticamente y la fuente cambia, Rasepi lo retraduce automáticamente. No es necesaria la intervención humana. El glosario y las normas de estilo mantienen la coherencia.

Cuando un párrafo ha sido editado manualmente por un traductor humano, quizá lo reescribió para darle un matiz cultural o añadió un contexto que una máquina no captaría, Rasepi respeta ese trabajo. Si la fuente cambia, el sistema marca el párrafo como necesitado de revisión pero nunca sobrescribe silenciosamente las ediciones humanas. El traductor ve lo que ha cambiado en la fuente y decide cómo actualizar su versión.

Esto significa que la calidad de su traducción mejora con el tiempo. La traducción automática se encarga del grueso. Los traductores humanos se centran en los párrafos que necesitan un toque humano. Y ninguno pisa el trabajo del otro.

Dos modos: siempre al día o traducir bajo demanda.

Para cada idioma, usted elige cuándo se realizan las traducciones:

Siempre traducir. Cada vez que alguien guarda el documento fuente, los párrafos modificados se vuelven a traducir inmediatamente. Lo mejor para sus idiomas más importantes, en los que los lectores esperan una precisión al minuto.
Traducir cuando se visualiza: Los párrafos modificados se marcan pero no se traducen hasta que alguien abre el documento en ese idioma. Estupendo para los idiomas que se utilizan con menos frecuencia. No desperdicie costes de traducción en contenidos que nadie lee.

Ambos modos utilizan el mismo glosario, las mismas normas de estilo, la misma calidad. La única diferencia es el tiempo.

Cómo se ve esto en la práctica

Supongamos que dirige una empresa con equipos en Londres, Múnich, París y Tokio. Su documentación está escrita en inglés.

Un responsable de producto en Londres actualiza la guía de despliegue. Una sección sobre un nuevo paso de CI/CD.

Esto es lo que ocurre

Alemán (siempre traducir). La sección modificada se vuelve a traducir en cuestión de segundos. "Sprint Review" se convierte en "Sprint-Überprüfung" porque eso está en su glosario. Formal "Sie" porque esa es su configuración de formalidad. Fechas en formato de 24 horas porque esa es su norma configurada. La instrucción personalizada "utilice un tono directo e imperativo" da forma al fraseo. ¿La sección DSGVO que añadió el equipo de Múnich? Sin tocar.
La misma sección, retraducida inmediatamente. Formalidad "Vous". Términos del glosario en francés aplicados. Símbolos de moneda después del número según sus instrucciones personalizadas. El resto del documento permanece exactamente como lo revisó la oficina de París por última vez.
Japonés (traducir al verlo). La sección modificada se marca como obsoleta. Cuando alguien en Tokio abre el documento, se traduce sobre la marcha. Su formato personalizado de lista numerada se conserva. Su nota de herramientas local permanece en su lugar.

Una edición. Tres idiomas actualizados. Cero retraducciones de documentos completos. Terminología coherente, tono coherente y respetuoso con las adiciones locales de cada equipo.

Hablando de calidad lingüística

El motor de traducción que hay detrás de todo esto es DeepL, la misma tecnología que impulsa la función Talk to Docs de Rasepi. Puede hablar a su documentación y obtener respuestas en voz alta. DeepL Voice se encarga de la interacción hablada, lo que significa que la misma coherencia terminológica, normas de estilo y calidad lingüística que obtiene en las traducciones escritas se traslada también a las conversaciones de voz. Los términos de su glosario y sus instrucciones personalizadas suenan correctamente tanto si su equipo está leyendo como escuchando.

Las traducciones que suenan como su equipo no son un lujo. Para las empresas que operan en varios idiomas, son la diferencia entre la documentación en la que la gente confía y la documentación con la que la gente trabaja a su alrededor. Los glosarios, las normas de estilo, las instrucciones personalizadas, la retraducción inteligente y el contenido único por idioma lo hacen posible. Automáticamente, desde el primer día.

Su documentación debe sonar como su equipo en cada idioma. No como una máquina. No como una empresa diferente. Como usted.

Vea la publicación multilingüe en acción →

Dentro del motor de traducción: Glosarios, reglas de estilo y retraducción inteligente

2026-03-31T00:00:00Z

Nuestro post anterior sobre arquitectura cubría los plugins, los guardianes de acción y el sistema de canalización. Éste profundiza en el motor de traducción, la parte que creo que hace que Rasepi sea fundamentalmente diferente de cualquier otra plataforma de documentación.

No el discurso de marketing sobre traducir párrafos en lugar de páginas. El código real. Cómo se resuelven los glosarios por inquilino, cómo las reglas de estilo de DeepL y las instrucciones personalizadas dan forma a cada traducción, cómo el hashing de contenidos impulsa la detección de documentos obsoletos y cómo el orquestador decide qué bloques hay que retraducir.

El proceso de traducción

Cuando un usuario guarda un documento, el sistema no se limita a retraducirlo todo. Ejecuta una secuencia bastante específica:

Analiza el JSON de TipTap en bloques individuales
Compara los hashes de contenido para detectar qué bloques cambiaron realmente
Para los bloques cambiados, resuelva el glosario del inquilino y la lista de reglas de estilo para el par de idiomas
Aplique las reglas de estilo, las instrucciones personalizadas y la formalidad de la configuración del arrendatario
Envíe sólo los bloques modificados a DeepL
Actualice los bloques de traducción y sincronice los hashes de contenido

Cada paso es su propio servicio con su propia interfaz. Esto es importante porque cualquier paso puede cambiarse por otra cosa, un proveedor de traducción diferente, un algoritmo hash diferente, una fuente de glosario diferente.

Resolución del glosario: tenant-scoped, DeepL-synced

DeepL glosarios tienen una limitación que la mayoría de la gente desconoce: son inmutables. No se puede editar un glosario DeepL. Cualquier cambio implica borrar el antiguo y crear uno nuevo.

Rasepi maneja esto tratando la base de datos como la fuente de la verdad y los glosarios de DeepL como artefactos desechables en tiempo de ejecución. La entidad TenantGlossary almacena todo localmente:

public class TenantGlossary : ITenantScoped
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public string Name { get; set; }
    public string SourceLanguage { get; set; }     // e.g. "en"
    public string TargetLanguage { get; set; }     // e.g. "de"
    public string? DeepLGlossaryId { get; set; }   // Runtime DeepL ID
    public DateTime? LastSyncedAt { get; set; }
    public bool IsDirty { get; set; } = true;      // Triggers re-sync
    public ICollection<TenantGlossaryEntry> Entries { get; set; }
}

Cuando un usuario añade una entrada en el glosario, por ejemplo asignando "Sprint Review" a "Sprint-Überprüfung" para EN→DE, el registro de la base de datos se actualiza inmediatamente y IsDirty se establece en true. El glosario DeepL no se recrea en ese momento. Se recrea perezosamente, la próxima vez que una traducción lo necesite realmente.

El flujo de sincronización

Antes de cada llamada a traducción, el sistema resuelve el glosario:

public async Task<string?> GetOrSyncDeepLGlossaryIdAsync(
    string sourceLanguage, string targetLanguage,
    CancellationToken ct = default)
{
    var glossary = await _db.TenantGlossaries
        .Include(g => g.Entries)
        .FirstOrDefaultAsync(g =>
            g.SourceLanguage == sourceLanguage &&
            g.TargetLanguage == targetLanguage, ct);

    if (glossary is null || glossary.Entries.Count == 0)
        return null;

    if (!glossary.IsDirty && glossary.DeepLGlossaryId is not null)
        return glossary.DeepLGlossaryId;

    // Dirty - delete old, create new
    if (glossary.DeepLGlossaryId is not null)
        await _deepL.DeleteGlossaryAsync(glossary.DeepLGlossaryId);

    var entries = glossary.Entries
        .ToDictionary(e => e.SourceTerm, e => e.TargetTerm);

    var deepLGlossary = await _deepL.CreateGlossaryAsync(
        $"rasepi-{glossary.Id}",
        glossary.SourceLanguage,
        glossary.TargetLanguage,
        entries);

    glossary.DeepLGlossaryId = deepLGlossary.GlossaryId;
    glossary.IsDirty = false;
    glossary.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync(ct);

    return glossary.DeepLGlossaryId;
}

Aquí hay tres cosas que merece la pena destacar:

Sincronización perezosa. Sólo llamamos a la API DeepL cuando realmente se necesita una traducción. La edición masiva de entradas del glosario no desencadena docenas de llamadas a la API.
**La consulta se ejecuta a través de los filtros de consulta globales de EF, por lo que TenantGlossaries se delimita automáticamente. Las entradas del glosario del arrendatario A nunca se filtran a las traducciones del arrendatario B.
Un glosario por par de idiomas. DeepL impone esto de todos modos. Un glosario EN→DE, un glosario EN→FR, y así sucesivamente. El par (SourceLanguage, TargetLanguage) es único por arrendatario.

Entradas del glosario

Las entradas individuales son sólo mapeos de términos:

public class TenantGlossaryEntry
{
    public Guid Id { get; set; }
    public Guid GlossaryId { get; set; }
    public string SourceTerm { get; set; }   // e.g. "Sprint Review"
    public string TargetTerm { get; set; }   // e.g. "Sprint-Überprüfung"
}

La API le ofrece CRUD completo además de importación/exportación CSV para la gestión en bloque:

POST   /api/admin/glossaries                       Create glossary
POST   /api/admin/glossaries/{id}/entries           Add term
PUT    /api/admin/glossaries/{id}/entries/{entryId}  Update term
DELETE /api/admin/glossaries/{id}/entries/{entryId}  Remove term
POST   /api/admin/glossaries/{id}/import            Import CSV
GET    /api/admin/glossaries/{id}/export            Export CSV
POST   /api/admin/glossaries/{id}/sync              Force DeepL sync

La importación CSV es súper útil para los equipos que migran desde sistemas de memorias de traducción existentes. Exporte sus términos, límpielos, impórtelos en Rasepi y la siguiente ejecución de traducción utilizará el nuevo glosario automáticamente.

Reglas de estilo, instrucciones personalizadas y formalidad

Los glosarios se ocupan de la terminología. Pero la terminología es sólo la mitad. Una traducción puede utilizar todas las palabras correctas y aun así sonar mal. Un tono incorrecto, un formato de fecha incorrecto, convenciones de puntuación incorrectas.

La API de reglas de estilo (v3) de DeepL lo soluciona. Puede crear listas de reglas de estilo reutilizables que combinan dos tipos de controles:

Reglas configuradas, convenciones de formato predefinidas para fechas, horas, puntuación, números, etc.
Instrucciones personalizadas, directivas de texto libre que dan forma al tono, la redacción y las convenciones específicas del dominio.

Rasepi las crea y gestiona por inquilino, por idioma de destino. La entidad TenantStyleRuleList almacena el DeepL style_id junto con las reglas configuradas y las instrucciones personalizadas del inquilino:

public class TenantStyleRuleList : ITenantScoped
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public string Name { get; set; }
    public string TargetLanguage { get; set; }      // e.g. "de"
    public string? DeepLStyleId { get; set; }       // Runtime DeepL style_id
    public string ConfiguredRulesJson { get; set; }  // Serialized configured rules
    public bool IsDirty { get; set; } = true;
    public DateTime? LastSyncedAt { get; set; }
    public ICollection<TenantCustomInstruction> CustomInstructions { get; set; }
}

Creación de listas de reglas de estilo

Cuando un administrador configura reglas de traducción para el alemán, Rasepi llama a la API v3 de DeepL para crear la lista de reglas de estilo. Esto es lo que parece:

public async Task<string> CreateOrSyncStyleRuleListAsync(
    TenantStyleRuleList ruleList, CancellationToken ct = default)
{
    if (!ruleList.IsDirty && ruleList.DeepLStyleId is not null)
        return ruleList.DeepLStyleId;

    // DeepL style rule lists are mutable - we can update in place
    if (ruleList.DeepLStyleId is not null)
    {
        // Replace configured rules on existing list
        await _httpClient.PutAsJsonAsync(
            $"v3/style_rules/{ruleList.DeepLStyleId}/configured_rules",
            JsonSerializer.Deserialize<JsonElement>(ruleList.ConfiguredRulesJson),
            ct);

        // Sync custom instructions
        await SyncCustomInstructionsAsync(ruleList, ct);

        ruleList.IsDirty = false;
        ruleList.LastSyncedAt = DateTime.UtcNow;
        return ruleList.DeepLStyleId;
    }

    // Create new style rule list
    var payload = new
    {
        name = $"rasepi-{ruleList.TenantId}-{ruleList.TargetLanguage}",
        language = ruleList.TargetLanguage,
        configured_rules = JsonSerializer.Deserialize<JsonElement>(
            ruleList.ConfiguredRulesJson),
        custom_instructions = ruleList.CustomInstructions.Select(ci => new
        {
            label = ci.Label,
            prompt = ci.Prompt,
            source_language = ci.SourceLanguage
        })
    };

    var response = await _httpClient.PostAsJsonAsync("v3/style_rules", payload, ct);
    var result = await response.Content.ReadFromJsonAsync<StyleRuleResponse>(ct);

    ruleList.DeepLStyleId = result.StyleId;
    ruleList.IsDirty = false;
    ruleList.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync(ct);

    return ruleList.DeepLStyleId;
}

A diferencia de los glosarios, las listas de reglas de estilo de DeepL son mutables. Puede reemplazar las reglas configuradas en su lugar con PUT /v3/style_rules/{style_id}/configured_rules, y las instrucciones personalizadas pueden añadirse, actualizarse o eliminarse individualmente. Mucho más amigable para el refinamiento iterativo.

Qué aspecto tienen las reglas configuradas

Las reglas configuradas cubren convenciones de formato que varían según el idioma o las preferencias de la empresa. Cosas como

{
  "dates_and_times": {
    "time_format": "use_24_hour_clock",
    "calendar_era": "use_bc_and_ad"
  },
  "punctuation": {
    "periods_in_academic_degrees": "do_not_use"
  },
  "numbers": {
    "decimal_separator": "use_comma"
  }
}

Parecen triviales, pero se complican rápidamente. Un documento alemán que utiliza el formato de hora AM/PM y decimales separados por puntos sólo se lee como "traducido del inglés" para un lector alemán. Establecer use_24_hour_clock y use_comma para los separadores decimales en todas las traducciones al alemán elimina eso inmediatamente.

Instrucciones personalizadas: éste es el verdadero poder

Las instrucciones personalizadas son directivas de texto libre, hasta 200 por lista de reglas de estilo, cada una de hasta 300 caracteres. Básicamente le dicen a DeepL cómo dar forma a la traducción en lenguaje llano:

public class TenantCustomInstruction
{
    public Guid Id { get; set; }
    public Guid StyleRuleListId { get; set; }
    public string Label { get; set; }              // e.g. "Tone instruction"
    public string Prompt { get; set; }             // e.g. "Use a friendly, diplomatic tone"
    public string? SourceLanguage { get; set; }    // Optional source lang filter
}

Ejemplos reales de nuestros inquilinos:

"Use a friendly, diplomatic tone" para una startup que quiere documentos accesibles
"Always use 'Sie' form, never 'du'" para un bufete de abogados alemán
"Translate 'deployment' as 'Bereitstellung', never 'Deployment'" para términos que necesitan un tratamiento dependiente del contexto más allá del simple mapeo del glosario
"Use British English spelling (colour, organisation, licence)" para empresas con sede en el Reino Unido que traducen entre variantes del inglés
"Put currency symbols after the numeric amount" para adaptarse a las convenciones europeas

Las instrucciones personalizadas son realmente potentes para las convenciones específicas de un dominio que no caben en las entradas de un glosario. Un glosario asigna un término a otro. Una instrucción personalizada puede decir "cuando traduzca documentos de la API, utilice el modo imperativo en lugar de la voz pasiva". Ese es un tipo de control completamente diferente.

Formalidad

El parámetro formality de DeepL (default, more, less, prefer_more, prefer_less) sigue estando disponible como control independiente junto con las reglas de estilo. El "du" alemán frente al "Sie", el "tu" francés frente al "vous", los niveles de cortesía japoneses. Estos se establecen por idioma del inquilino a través de TenantLanguageConfig:

public class TenantLanguageConfig : ITenantScoped
{
    public string LanguageCode { get; set; }
    public string DisplayName { get; set; }
    public bool IsEnabled { get; set; }
    public TranslationTrigger Trigger { get; set; }
    public string? Formality { get; set; }         // "more", "less", "prefer_more", etc.
    public string? StyleRuleListId { get; set; }   // Links to TenantStyleRuleList
    public string? TranslationProvider { get; set; }
    public int SortOrder { get; set; }
    public bool IsDefault { get; set; }
}

La formalidad, las normas de estilo y los glosarios se componen. Una sola llamada de traducción puede llevar los tres:

var glossaryId = await GetOrSyncDeepLGlossaryIdAsync(sourceLang, targetLang, ct);
var styleId = await GetOrSyncStyleRuleListAsync(targetLang, ct);
var formality = tenantLanguageConfig.Formality ?? "default";

// Build the v2/translate request payload
var payload = new
{
    text = new[] { blockContent },
    source_lang = NormalizeLanguageCode(sourceLang),
    target_lang = NormalizeLanguageCode(targetLang),
    glossary_id = glossaryId,
    style_id = styleId,
    formality = formality,
    preserve_formatting = true,
    context = surroundingContext,  // Adjacent blocks, not billed
    model_type = "quality_optimized"
};

Aquí hay que señalar dos cosas:

El parámetro context. Pasamos bloques adyacentes como contexto para mejorar la calidad de la traducción. DeepL lo utiliza para resolver ambigüedades, pero no traduce ni factura por ello. Un párrafo sobre "celdas" se traduce de forma diferente cuando el contexto circundante es un documento de biología frente a un manual de hojas de cálculo.
Selección del modelo. Cualquier solicitud con style_id o custom_instructions utiliza automáticamente el modelo quality_optimized de DeepL. Este es el nivel de calidad más alto. No puede combinarlos con latency_optimized, y es una restricción deliberada de DeepL. La personalización del estilo necesita el modelo completo.

Por qué esto importa más de lo que cree

Imagine una empresa que escribe documentos internos en alemán con un "du" informal que de repente cambia a un "Sie" formal en una sección traducida. Parece incoherente en el mejor de los casos, poco profesional en el peor. La formalidad se encarga de eso. Pero la formalidad por sí sola no detectará un documento que utiliza marcas de tiempo AM/PM cuando su oficina alemana utiliza el formato de 24 horas, o que pone el símbolo de la moneda antes del número en lugar de después.

Todas estas capas juntas (reglas de estilo, instrucciones personalizadas, formalidad, glosarios) producen traducciones que se leen como si alguien de su equipo las hubiera escrito. No como salidas de una máquina que no sabe que su empresa existe.

La capa de servicio DeepL

Toda la comunicación de DeepL pasa por IDeepLService. Envuelve el SDK .NET oficial de DeepL y gestiona las llamadas a la API v3 para las reglas de estilo:

public interface IDeepLService
{
    // Text translation (v2)
    Task<TextResult> TranslateTextAsync(
        string text, string sourceLanguage, string targetLanguage,
        string? options = null);

    Task<TextResult[]> TranslateTextBatchAsync(
        IEnumerable<string> texts, string sourceLanguage,
        string targetLanguage, string? options = null);

    // Glossary management (v2)
    Task<GlossaryInfo> CreateGlossaryAsync(
        string name, string sourceLang, string targetLang,
        Dictionary<string, string> entries);
    Task DeleteGlossaryAsync(string glossaryId);
    Task<GlossaryInfo> GetGlossaryAsync(string glossaryId);
    Task<GlossaryInfo[]> ListGlossariesAsync();
    Task<Dictionary<string, string>> GetGlossaryEntriesAsync(
        string glossaryId);

    // Style rules (v3)
    Task<StyleRuleResponse> CreateStyleRuleListAsync(
        string name, string language,
        JsonElement configuredRules,
        IEnumerable<CustomInstructionRequest> customInstructions);
    Task ReplaceConfiguredRulesAsync(
        string styleId, JsonElement configuredRules);
    Task<CustomInstructionResponse> AddCustomInstructionAsync(
        string styleId, string label, string prompt,
        string? sourceLanguage = null);
    Task DeleteCustomInstructionAsync(
        string styleId, string instructionId);
    Task DeleteStyleRuleListAsync(string styleId);

    // Usage tracking
    Task<Usage> GetUsageAsync();
    Task<Language[]> GetSourceLanguagesAsync();
    Task<Language[]> GetTargetLanguagesAsync();
}

La implementación gestiona la normalización del código del lenguaje. DeepL requiere EN-US o EN-GB en lugar de en desnudo, y PT-PT o PT-BR en lugar de pt:

private static string NormalizeLanguageCode(string code)
    => code.ToLower() switch
    {
        "en" => "EN-US",
        "pt" => "PT-PT",
        _ => code.ToUpper()
    };

La traducción por lotes utiliza el troceado de 50 elementos para mantenerse dentro de los límites de la API de DeepL al tiempo que se maximiza el rendimiento:

public async Task<TranslationBatchResult> TranslateBatchAsync(
    Dictionary<string, string> texts,
    string sourceLanguage, string targetLanguage)
{
    var translations = new Dictionary<string, string>();
    long totalChars = 0;

    foreach (var chunk in texts.Chunk(50))
    {
        var results = await _deepL.TranslateTextBatchAsync(
            chunk.Select(kv => kv.Value),
            sourceLanguage, targetLanguage);

        for (int i = 0; i < chunk.Length; i++)
        {
            translations[chunk[i].Key] = results[i].Text;
            totalChars += chunk[i].Value.Length;
        }
    }

    return new TranslationBatchResult
    {
        Translations = translations,
        BilledCharacters = totalChars
    };
}

Dado que sólo enviamos bloques anticuados, no documentos enteros, un lote de traducción típico para una sola edición contiene de 1 a 3 bloques en lugar de más de 40. De ahí procede la reducción de costes del 94%.

El orquestador de traducción

El TranslationOrchestrator decide qué hacer con cada bloque cuando cambia el documento fuente. Recorramos el árbol de decisiones:

public async Task OrchestrateTranslationAsync(
    Guid entryId, List<Guid> changedBlockIds,
    CancellationToken ct = default)
{
    var entry = await _db.Entries
        .FirstOrDefaultAsync(e => e.Id == entryId, ct);

    var translations = await _db.EntryTranslations
        .Where(t => t.EntryId == entryId)
        .ToListAsync(ct);

    foreach (var translation in translations)
    {
        var langConfig = await GetLanguageConfigAsync(
            translation.Language, ct);

        var translationBlocks = await _db.TranslationBlocks
            .Where(tb => changedBlockIds.Contains(tb.SourceBlockId)
                      && tb.Language == translation.Language)
            .ToListAsync(ct);

        foreach (var block in translationBlocks)
        {
            if (block.IsLocked || block.TranslatedById is not null)
            {
                // Human-edited or locked - mark stale, don't overwrite
                block.Status = TranslationStatus.Stale;
            }
            else if (langConfig.Trigger == TranslationTrigger.AlwaysTranslate)
            {
                // Machine-translated, auto mode - retranslate now
                await RetranslateBlockAsync(block, translation.Language, ct);
            }
            else
            {
                // TranslateOnFirstVisit - mark stale, translate later
                block.Status = TranslationStatus.Stale;
            }
        }
    }

    await _db.SaveChangesAsync(ct);
}

El bit clave: Los bloques editados por humanos nunca se sobrescriben automáticamente. Si un traductor ajustó manualmente un bloque, quizá añadiendo contexto cultural o reformulando la redacción para mayor claridad, el sistema respeta ese trabajo. Marca el bloque como obsoleto para que el traductor sepa que la fuente ha cambiado, pero no reemplazará silenciosamente sus ediciones.

Los bloques traducidos automáticamente con AlwaysTranslate activado se retraducen inmediatamente. Los bloques traducidos automáticamente con TranslateOnFirstVisit se marcan como obsoletos y se traducen cuando alguien abre el documento en ese idioma.

Activadores de traducción: cuándo se producen las traducciones

Cada idioma tiene un TranslationTrigger que controla los tiempos:

public enum TranslationTrigger
{
    AlwaysTranslate,         // Translate on every save
    TranslateOnFirstVisit    // Translate when first opened in that language
}

AlwaysTranslate es útil para los idiomas de alta prioridad en los que desea que las traducciones estén inmediatamente actualizadas. Francés para una empresa con una gran oficina en París. Alemán para una empresa con sede en Múnich.

TranslateOnFirstVisit es útil para idiomas que se necesitan ocasionalmente pero no merece la pena el coste API de mantener perfectamente actualizados en todo momento. Cuando alguien abre el documento en ese idioma, los bloques obsoletos se traducen sobre la marcha.

Ambos modos utilizan la misma resolución de glosario, los mismos ajustes de formalidad y el mismo hashing de contenido. La única diferencia es el tiempo.

Adaptación única del contenido y la estructura

Aquí es donde la arquitectura realmente vale la pena más allá de la mera traducción.

Cuando un traductor alemán añade una sección de cumplimiento de la DSGVO que no existe en inglés, la añade como un nuevo bloque en la versión alemana. Ese bloque no tiene SourceBlockId, está marcado como contenido único. El sistema nunca lo envía para retraducción porque no hay fuente de la que traducir. Sólo existe en alemán.

Cuando un traductor japonés cambia una lista con viñetas por una lista numerada (una convención común en la escritura técnica japonesa), la bandera IsStructureAdapted del bloque lo conserva en futuros ciclos de retraducción:

var translation = new TranslationBlock
{
    SourceBlockId = sourceBlockId,
    Language = targetLanguage,
    BlockType = translatedBlockType,
    SourceBlockType = sourceBlock.BlockType,
    IsStructureAdapted = translatedBlockType != sourceBlock.BlockType,
    StructureAdaptationNotes = "Numbered list preferred in JP technical docs",
    SourceContentHash = sourceBlock.ContentHash,
    Status = TranslationStatus.UpToDate,
};

La bandera IsNoTranslate se encarga del contenido que debe copiarse textualmente: bloques de código, URL, nombres de productos, notación matemática. El proveedor de traducción se los salta por completo.

Ponerlo todo junto

Recorramos el flujo completo. Un usuario en Londres edita un párrafo en el documento fuente en inglés, y su oficina de Múnich tiene el alemán configurado en AlwaysTranslate:

El usuario guarda. TipTap envía JSON a la API.
Extracción de bloques y detección de cambios. CreateBlocksFromDocumentAsync analiza JSON, recalcula los hashes de contenido y compara los hashes antiguos y nuevos para identificar qué bloques cambiaron realmente.
El orquestador se ejecuta. Encuentra el EntryTranslation alemán, comprueba el bloque alemán. Está traducido por máquina, no está bloqueado y no ha sido editado por humanos, por lo que es apto para la retraducción.
Configuración de traducción cargada. ID del glosario resuelto mediante GetOrSyncDeepLGlossaryIdAsync("en", "de"), reglas de estilo mediante GetOrSyncStyleRuleListAsync("de"), formalidad establecida en "más" (formal "Sie"), bloques adyacentes pasados como contexto para desambiguación.
Llamada DeepL. Se envía un único bloque con el ID del glosario, el ID del estilo, la formalidad y el contexto.
Bloque actualizado. Contenido traducido almacenado, SourceContentHash sincronizado, estado establecido en UpToDate. Un bloque traducido en lugar de los más de 40. ¿Los 39 bloques restantes? Intactos.

Mientras tanto, su oficina de Tokio tiene el japonés fijado en TranslateOnFirstVisit. La misma edición marca el bloque de traducción japonés como Stale. Cuando alguien en Tokio abre el documento, los pasos 5-9 suceden sobre la marcha. La adaptación de su estructura (lista numerada) se conserva. Sus bloques únicos permanecen exactamente donde están.

Creo que el motor de traducción es la parte de Rasepi que aporta el valor más visible. Traducciones que utilizan su terminología, siguen sus convenciones de formato, obedecen sus instrucciones personalizadas, coinciden con su tono, respetan el trabajo de sus traductores y cuestan una fracción de lo que costaría la retraducción de un documento completo. La arquitectura hace que todo eso sea automático, y se mantiene al margen cuando los humanos quieren tomar el relevo.

El mismo motor DeepL que impulsa las traducciones escritas también impulsa Talk to Docs, nuestra interfaz de documentación conversacional, con DeepL Voice encargándose de la interacción hablada. Los mismos glosarios, las mismas normas de estilo, la misma formalidad, la misma coherencia. Tanto si su equipo lee la documentación como si habla con ella, la calidad lingüística es idéntica.

Explore la API de traducción →

Deje de mantener cinco copias del mismo documento

2026-03-31T00:00:00Z

Abra ahora mismo la wiki de su empresa y busque "onboarding". ¿Cuántos resultados obtiene?

Si es una empresa global, supongo que no es ni uno. Probablemente sea algo como esto:

Onboarding Guide (EN)
Onboarding Guide - Germany
Onboarding Guide - Japan
BLOQUE DE CÓDIGO 3
BLOQUE DE CÓDIGO 4

Cinco documentos. Todos cubren aproximadamente lo mismo. Todos ligeramente diferentes. Todos mantenidos por diferentes personas con diferentes calendarios. Algunos actuales, otros con tres meses de retraso, uno del que ya nadie está seguro.

Esto es lo que ocurre cuando su plataforma de documentación no puede manejar correctamente el contenido multilingüe. Acaba copiando todo el documento para cada mercado, y cada copia se aleja poco a poco de las demás.

La trampa de copiar y localizar

Todo empieza de forma bastante inocente. Usted tiene una estupenda guía de incorporación en inglés. La oficina de Berlín la necesita en alemán, así que alguien la copia, la traduce y añade las partes específicas de Alemania: formación sobre la DSGVO, información sobre el Betriebsrat, inscripción en el seguro médico local.

Entonces Tokio necesita una. Copiar de nuevo. Traduzca. Añada las cosas específicas de Japón: inscripción en el hanko, proceso de obtención del abono de transporte, guía de etiqueta en la oficina.

São Paulo es la siguiente. Lo mismo. Copie, traduzca, añada contenido local sobre los requisitos del CLT, los vales de comida y los documentos fiscales.

Ahora tiene cuatro documentos. El original en inglés se actualiza regularmente. La versión alemana se actualizó el trimestre pasado. La versión japonesa... alguien cree que Tanaka-san la actualizó en octubre. La versión brasileña fue creada por un contratista que se marchó, y nadie la ha tocado desde entonces.

Cada copia es una carga de mantenimiento. Y cada una de ellas contiene una mezcla de contenido compartido (lo que es igual en todas partes) y contenido local (lo específico de ese mercado). Pero la plataforma no distingue la diferencia. Todo es sólo texto en una página.

Así que cuando alguien actualiza la sección de política de seguridad en el original inglés, nadie actualiza las otras cuatro. O peor aún, alguien actualiza la alemana pero no la japonesa. Ahora tiene cinco documentos que dicen todos cosas ligeramente diferentes sobre la misma política de empresa.

El verdadero problema: el contenido compartido y el local se mezclan

La cuestión es que la mayoría de estos documentos son idénticos en un 70-80%. Los pasos de incorporación, la configuración de las herramientas, las políticas de seguridad, la sección de valores de la empresa, la lista de "a quién contactar". Todo eso es lo mismo independientemente de si está en Berlín, Tokio o São Paulo.

Lo local es quizá el 20-30% del documento. Requisitos de cumplimiento específicos, beneficios locales, procesos regionales, contactos del equipo para esa oficina.

Pero cuando todo vive en un gran documento plano por idioma, no hay forma de saber qué partes son compartidas y cuáles son locales. Una actualización del contenido compartido implica comprobar y actualizar manualmente cada copia. Lo que nadie hace sistemáticamente. Por eso las copias van a la deriva.

Un documento. Eso es todo.

En Rasepi, la guía de incorporación es un solo documento. No uno por idioma. Uno.

El contenido compartido, el 70-80% que es el mismo en todas partes, se escribe una vez en inglés y se traduce automáticamente a todos los idiomas que utiliza su equipo. Cuando alguien actualiza la sección de política de seguridad en inglés, se vuelve a traducir en alemán, japonés, portugués y francés en cuestión de segundos. Sin copias manuales. Nada de "alguien debería actualizar las otras versiones".

El contenido local vive en su respectiva versión lingüística. La sección de formación de la DSGVO sólo existe en la versión alemana. El proceso hanko sólo existe en la versión japonesa. Los requisitos CLT sólo existen en la versión portuguesa. Estas secciones están marcadas como contenido único, pertenecen a ese idioma y nunca se sobrescriben con la retraducción.

Cubrimos exactamente cómo funciona esto en nuestro post sobre cómo funcionan las traducciones de Rasepi. La versión resumida: cada párrafo tiene su propia identidad. Los párrafos compartidos se traducen y se les hace un seguimiento. Los párrafos únicos pertenecen a su idioma y nada más los toca.

¿El resultado? Su búsqueda en la wiki de "onboarding" devuelve un solo resultado. Sólo "Onboarding". Ábralo en inglés, verá la versión inglesa con todo el contenido compartido. Ábralo en alemán, verá el mismo contenido compartido en alemán más las secciones específicas de Alemania. Ábralo en japonés, el mismo contenido compartido en japonés más las secciones específicas de Japón.

Un documento. No cinco. No cinco documentos pudriéndose lentamente a diferentes velocidades.

Lo que esto cambia en realidad

Esto no es sólo más ordenado. Cambia fundamentalmente el funcionamiento de su documentación en todas las oficinas.

Las actualizaciones llegan realmente a todos

Cuando actualiza la parte compartida de la guía de incorporación, se actualiza en todos los idiomas. No con el tiempo, ni después de que alguien se acuerde de hacerlo. Se actualiza automáticamente. El párrafo que ha cambiado se vuelve a traducir. Todo lo demás se queda exactamente donde estaba.

Esto significa que su oficina de Tokio está leyendo la misma política de empresa que su oficina de Londres. No la versión de hace seis meses que nadie se puso a actualizar.

Los equipos locales son dueños de su contenido local

Su equipo de Múnich puede añadir una sección sobre el descuento del gimnasio local sin preocuparse de que sea borrada por la próxima actualización inglesa. Su contenido único es suyo. Permanece en la versión alemana, intacto ante cualquier cambio en la fuente inglesa.

Lo mismo para el resto. El contenido local es genuinamente local. No interfiere con el contenido compartido, y el contenido compartido no interfiere con él.

Los recién contratados reciben la información adecuada.

Un recién contratado en São Paulo abre la guía de incorporación y ve todo lo que necesita. Las secciones compartidas (herramientas, seguridad, valores) están en portugués. Las secciones específicas de Brasil (CLT, documentos fiscales, vales de comida) están ahí al lado. Un solo documento, todo en su idioma, no falta nada, nada está desfasado.

No necesitan saber que otras tres oficinas tienen secciones locales diferentes. Sólo ven su versión. Limpia y completa.

Disminuye el número de páginas

Esta es la matemática simple. Si tiene 50 documentos clave y los mantiene en 5 idiomas con el método de copiar y localizar, tiene 250 documentos. En Rasepi, tiene 50. Cada uno con versiones lingüísticas que comparten contenidos comunes y mantienen sus propias secciones locales.

250 documentos que mantener frente a 50. Son 200 páginas de sobrecarga de mantenimiento que desaparecen.

No se trata sólo de la incorporación

La incorporación es el ejemplo obvio porque todas las empresas globales tienen este problema. Pero el mismo patrón aparece en todas partes:

Guías de implantación. Los pasos básicos son los mismos, pero el equipo de Berlín utiliza un servidor de puesta en escena local y Tokio tiene un proceso de aprobación diferente.
Documentación de cumplimiento. Sección GDPR para Europa, LGPD para Brasil, APPI para Japón. Todo en el mismo documento, cada uno aparece sólo donde es relevante.
Beneficios y políticas de RR.HH. La política de permiso parental es diferente en cada país. Los valores de la empresa son los mismos en todas partes.
Documentos de ayuda orientados al cliente. El producto funciona igual en todas partes, pero las formas de pago, los horarios de asistencia y las normativas regionales varían.

Cada uno de ellos es un documento que la mayoría de las empresas mantienen como copias separadas por mercado. Y cada uno de ellos podría ser un único documento con contenido compartido y local.

El efecto compuesto

Aquí es donde se vuelve real. Una empresa con 200 documentos en 4 mercados no está manteniendo 200 documentos. Están manteniendo 800. Pero tienen personal para 200. Así que lo que realmente sucede es:

Las versiones inglesas están actualizadas
Las versiones alemanas están actualizadas en su mayor parte
Las versiones francesas están atrasadas
Las versiones japonesas son una incógnita

¿Le suena?

En Rasepi mantienen 200 documentos. El contenido compartido se traduce automáticamente. El contenido local lo añaden los equipos locales. Cada versión es tan actual como la inglesa, más los añadidos locales que haya hecho el equipo regional.

Los costes de traducción también son menores. Cuando se actualiza un párrafo en inglés, sólo ese párrafo se vuelve a traducir en todos los idiomas. No todo el documento, ni los 200 documentos. Sólo el párrafo que realmente ha cambiado. Hemos escrito sobre cómo funciona en detalle, incluyendo el glosario y las reglas de estilo que hacen que el contenido traducido suene natural.

Una rápida comprobación visceral

Si dirige un equipo global, pregúntese:

¿Cuántos documentos duplicados tiene? Busque el mismo tema y cuente las copias específicas de cada idioma.
**Compruebe la fecha de la última edición de sus documentos en alemán, francés o japonés. ¿Cuánto retraso tienen?
¿Añaden los equipos locales contenido a sus versiones? ¿O han desistido porque se sobrescribe?
¿Cuánto tarda el onboarding en las oficinas que no hablan inglés? Si es más largo, lo más probable es que la documentación no les esté sirviendo adecuadamente.

Si las respuestas le incomodan, no está solo. La mayoría de las empresas no se dan cuenta de los gastos generales que han creado hasta que realmente cuentan las copias.

La documentación debe escalar con su empresa, no multiplicarse. Cada copia que mantiene es una copia que puede quedarse atrás, confundir a un nuevo empleado o contradecir la versión que está leyendo otra persona. Un documento por tema, con el contenido compartido traducido y el contenido local donde corresponde, es como debe funcionar la documentación en una empresa global.

Su wiki no debería necesitar cinco copias del mismo documento. Una es suficiente. Pasos compartidos traducidos, pasos locales por idioma. Eso es todo.

Vea la publicación multilingüe en acción →

El argumento comercial a favor de la localización a nivel de bloque

2026-03-24T00:00:00Z

Existe un patrón en todas las empresas que operan más allá de sus fronteras. La documentación en inglés es sólida. La versión alemana lleva tres meses de retraso. La versión japonesa fue traducida una vez, por un contratista, y nadie la ha tocado desde entonces. La versión brasileña en portugués aún no existe, a pesar de que São Paulo es la oficina de mayor crecimiento.

Todo el mundo está de acuerdo en que esto es un problema. Nadie tiene una buena solución. Hasta ahora, la localización se ha tratado como un proyecto, un esfuerzo de una sola vez que se presupuesta, se ejecuta y luego se descuida en silencio hasta la próxima gran revisión.

Ese enfoque está roto. He aquí por qué, y lo que creo que realmente funciona.

La traducción no es localización

Aclaremos la terminología. Traducir es tomar un texto en un idioma y producir un texto equivalente en otro. La localización es hacer que los conocimientos funcionen en un mercado específico. Se solapan, pero no son lo mismo.

Un documento traducido se lee correctamente. Un documento localizado se lee con naturalidad. Tiene en cuenta el contexto cultural, la normativa regional, las herramientas locales y la forma en que trabajan realmente las personas en ese mercado.

Esta distinción es importante porque la mayoría de las plataformas de documentación tratan la localización como una tarea de traducción. Usted escribe en inglés, pulsa un botón y obtiene la salida en francés. Listo. Excepto que no está hecho, porque:

El equipo francés tiene un proceso de despliegue diferente que el documento en inglés no cubre.
Los requisitos de conformidad alemanes añaden un paso de aprobación adicional que no existe en ningún otro lugar
La oficina japonesa utiliza una herramienta interna diferente para el mismo flujo de trabajo
Los lectores brasileños de portugués necesitan un contexto sobre las normas fiscales locales que no es relevante en ningún otro lugar

Una traducción directa del documento inglés es técnicamente correcta en todos estos casos, y prácticamente inútil en todos ellos también.

El problema de la traducción a nivel de documento

La localización tradicional funciona a nivel de documento. Usted tiene un documento en inglés. Usted lo traduce entero al alemán. Cuando cambia la versión inglesa, lo envía entero para que lo vuelvan a traducir. Esto crea tres problemas:

1. Es caro

Si su guía de incorporación tiene 15 secciones y cambia un párrafo, estará pagando por volver a traducir las 15 secciones. Multiplique eso por 8 idiomas y cada edición se convierte en una conversación presupuestaria.

2. Es lento

Enviar documentos completos para su traducción lleva tiempo. Incluso con la traducción automática moderna, el ciclo de revisión de un documento completo es significativamente más largo que la revisión de una sola sección modificada. Los equipos de otros idiomas siempre van con retraso.

3. No admite contenidos únicos

Este es el verdadero asesino. Si la versión alemana necesita una sección adicional sobre el cumplimiento de la DSGVO, ¿dónde va? En un sistema de traducción a nivel de documento, cualquier contenido añadido a la versión alemana se sobrescribe la próxima vez que alguien vuelve a traducir desde el inglés. El equipo alemán aprende rápido: no añada nada, porque se borrará.

Localización a nivel de bloque: una arquitectura diferente

Rasepi no traduce documentos. Traduce bloques: párrafos individuales, encabezados y secciones, cada uno rastreado de forma independiente con su propia identidad y hash de contenido.

Esto es lo que significa en la práctica:

Cuando edita un único párrafo en inglés, Rasepi detecta qué bloque ha cambiado comparando los hashes de contenido SHA256. Sólo ese bloque se envía para su traducción a través de DeepL. Los otros 14 bloques del documento permanecen exactamente como estaban. Su coste de traducción se reduce hasta en un 94%.

Cuando el traductor alemán necesita añadir una sección DSGVO, la añade como un nuevo bloque en la versión alemana. Ese bloque sólo existe en alemán. No afecta a la fuente en inglés. No se sobrescribe cuando cambia el inglés. Está marcado como contenido único para que todo el mundo sepa que es intencionado.

Cuando la versión japonesa necesita una estructura diferente, por ejemplo, una lista numerada en lugar de viñetas porque esa es la convención en la escritura técnica japonesa, el traductor puede cambiar el tipo de bloque. El sistema lo registra como una "adaptación de la estructura" y lo conserva en futuras actualizaciones.

Cada versión lingüística se convierte en un documento de primera clase, no en una copia sombra.

Cómo funciona, técnicamente

Cada bloque en Rasepi tiene

Un UUID que persiste a través de todas las ediciones y traducciones
Un hash de contenido (SHA256) que cambia cuando cambia el texto
Un índice de posición para que los bloques permanezcan en el orden correcto
Una bandera de borrado suave** para que la eliminación de un bloque en inglés no rompa la alineación en otros idiomas.

Cuando se crea un bloque de traducción, almacena el hash del contenido del bloque de origen. En cada guardado, el sistema compara los hashes. Si coinciden, la traducción es actual. Si no lo hacen, la traducción se marca como obsoleta, y sólo ese bloque específico necesita atención.

Este es el mecanismo que está detrás de la reducción de costes del 94%. La mayoría de las ediciones cambian una o dos secciones. El resto del documento, en todas las lenguas, permanece intacto.

Contenido único por idioma

Aquí es donde las cosas se ponen realmente diferentes de cualquier otra plataforma.

En Rasepi, cada versión lingüística puede contener:

Bloques traducidos. Traducciones directas del idioma de origen, rastreadas para comprobar que no se han quedado obsoletas.
Bloques únicos. Contenido que sólo existe en ese idioma, añadido por el equipo local
Bloques de estructura adaptada. Mismo contenido de origen, diferente formato o tipo de bloque

Un mismo documento podría tener este aspecto en todos los idiomas:

Bloque	Inglés (fuente)	Alemán	Japonés
1. Introducción. Traducido.
2	Pasos de la instalación	Traducido	Estructura adaptada (lista numerada)
3	-	Cumplimiento de la DSGVO (único)	-
4	Despliegue	Traducido	Traducción
5	-	Nota sobre herramientas locales (único)
6	Solución de problemas	Traducido	Traducción

Cada equipo recibe exactamente la documentación que necesita. Sin compromisos. Sin soluciones provisionales. Sin limitaciones de talla única.

Seguimiento de la actualización en todos los idiomas

Cada versión lingüística rastrea su propia frescura de forma independiente. La fuente en inglés podría puntuar 94 (revisado recientemente, todos los enlaces válidos, gran número de lectores). La versión francesa podría puntuar 71 (dos bloques obsoletos, un enlace roto específico del contenido francés). La versión japonesa podría puntuar 88 (todas las traducciones son actuales, pero el número de lectores está disminuyendo).

Este seguimiento de la frescura por idioma significa:

Usted sabe exactamente qué idiomas necesitan atención
Las traducciones obsoletas salen a la luz automáticamente, no se descubren por accidente.
Las herramientas de inteligencia artificial pueden tener en cuenta la actualización específica de cada idioma a la hora de ofrecer respuestas.
Los paneles de control muestran el estado de los contenidos desglosado por idiomas, no sólo por documentos.

El caso de negocio

Las empresas que operan en varios idiomas se enfrentan a una sencilla realidad: su documentación es un activo o un pasivo en todos los mercados en los que opera.

Cuando su equipo de Berlín trabaja a partir de una traducción al alemán que lleva tres meses de retraso con respecto a la fuente inglesa, están tomando decisiones basadas en información obsoleta. Cuando su oficina de Tokio no puede añadir contexto local a los documentos compartidos porque el sistema de traducción lo sobrescribiría, dejan de utilizar la wiki y crean su propia documentación en la sombra. Cuando su equipo de São Paulo no dispone de documentación en portugués, la incorporación tarda el doble.

El coste no es sólo de traducción. Lo es:

Incorporación más lenta en mercados no ingleses.
Esfuerzo duplicado ya que los equipos mantienen documentación paralela en herramientas locales
Silos de conocimiento que se forman cuando la wiki oficial no sirve para todos
Riesgo de cumplimiento cuando no se recogen los requisitos específicos de cada región
Pérdida de confianza en el propio sistema de documentación

La localización a nivel de bloque resuelve todos estos problemas, no abaratando la traducción (aunque lo hace), sino convirtiendo cada versión lingüística en un documento vivo, mantenido y digno de confianza.

Para empezar

Si hoy en día dirige un equipo multilingüe en cualquier plataforma de documentación, he aquí una rápida comprobación visceral:

Escoja su documento más importante. Revíselo en cada idioma. ¿Está actualizada cada versión?
Pregunte a sus equipos no ingleses: ¿Confían en los documentos traducidos? ¿Los utilizan?
Busque documentación en la sombra. ¿Los equipos mantienen wikis locales, páginas de Notion o mensajes anclados en Slack porque la documentación oficial no les sirve?
Calcule su gasto en traducción. ¿Cuánto está pagando por actualización, y cuánto de eso es retraducir contenido que no cambió?

Si las respuestas le incomodan, no está solo. La mayoría de las empresas no descubren la brecha hasta que causa un problema real: un problema de cumplimiento, una implantación chapucera, un nuevo empleado que se pasó dos semanas siguiendo instrucciones obsoletas.

El conocimiento multilingüe no es un "nice-to-have". Para cualquier empresa que opere a través de las fronteras, es la base de cómo los equipos se alinean, toman decisiones y realizan envíos. La cuestión es si su plataforma de documentación lo trata así.

Cada idioma merece ser un ciudadano de primera clase en su base de conocimientos. No una copia. No una sombra. Un documento real, mantenido y de confianza.

Eso es lo que ofrece Rasepi. Traducción a nivel de bloque, contenido único por idioma, seguimiento independiente de la frescura y una reducción del 94% en los costes de traducción. Todo automático. Todo desde el primer día.

Vea la publicación multilingüe en acción →

Frescura del contenido, parte 2: más allá de las fechas de caducidad

2026-03-18T00:00:00Z

Esta es la segunda parte de nuestra serie sobre frescura de contenidos. La Parte 1 cubre por qué importa la frescura y qué significa realmente. Este post retoma el tema donde lo dejó: por qué las fechas de caducidad por sí solas no son suficientes y cómo es la supervisión continua.

Digamos que usted hace lo responsable. Cada documento de su wiki tiene una fecha de revisión. Seis meses desde su creación, quizá doce para material de referencia estable. Cuando llega la fecha, el propietario recibe una notificación: revise esto o queda marcado.

Eso es mejor que lo que hacen la mayoría de las empresas. La mayoría de las empresas no hacen nada. El documento se queda ahí, deteriorándose lentamente, y nadie se da cuenta hasta que alguien sigue las instrucciones y algo se rompe.

Pero he aquí la incómoda verdad: las fechas de caducidad son necesarias y completamente insuficientes. He visto documentos que se vuelven peligrosamente caducos días después de su última revisión, y una fecha de revisión no lo detecta.

Qué solucionan realmente las fechas de caducidad

Las fechas de caducidad resuelven el problema de la rendición de cuentas. Responden a la pregunta: "¿Quién es el responsable de confirmar que esto sigue siendo exacto, y cuándo?"_.

Eso es realmente valioso. Sin ella, la documentación entra en lo que llamamos el vacío de propiedad, un estado en el que todo el mundo asume que alguien más la mantiene, por lo que nadie lo hace. Establecer una fecha de revisión asigna a una sola persona una única obligación en una fecha concreta. Sencillo. Claro. Eficaz.

He aquí cómo son las fechas de vencimiento en la práctica:

Se crea un documento con una fecha de revisión a 90 días vista.
14 días antes de la expiración, se notifica al propietario
En la fecha de vencimiento, el documento se marca como "necesita revisión"
El propietario lo revisa, confirma que sigue siendo correcto y amplía la fecha
O lo actualizan, o lo reasignan, o lo archivan

Este es un sistema sólido. Capta el deterioro lento, el documento en el que nadie ha pensado en un año. Crea una cadencia regular de revisión. Hace visible la propiedad.

Pero tiene un punto ciego del tamaño de un continente.

Lo que las fechas de caducidad pasan por alto

Entre las fechas de revisión, un documento vive en una caja negra. Usted lo revisó el 15 de enero. La próxima revisión es el 15 de abril. El 3 de febrero podría ocurrir cualquiera de estas cosas:

Los enlaces se rompen silenciosamente

Una URL externa a la que ha hecho referencia devuelve un 404. Un enlace interno apunta a un documento que fue archivado. Un repositorio de código fue renombrado y cada enlace GitHub en su documento está ahora muerto. Su documento aún se ve bien. La fecha de caducidad no es hasta dentro de dos meses. Nadie sabe que los enlaces están rotos.

Cambios de contenido relacionados

Usted escribió una guía de despliegue que hace referencia a su documento de arquitectura. En febrero, alguien reescribe por completo el documento de arquitectura. Nuevos patrones, nueva infraestructura, nuevas convenciones. Su guía de despliegue sigue haciendo referencia a la antigua arquitectura. Aún no está técnicamente mal, pero va a la deriva. Para cuando llegue su fecha de revisión, la brecha puede ser significativa.

El número de lectores cae a cero

Su documento solía ser leído por 40 personas al mes. Luego cambió un proceso y ya nadie lo necesita, pero tampoco nadie lo archivó. Permanece en los resultados de búsqueda, ocupando espacio, confundiendo ocasionalmente a un nuevo empleado que no sabe que es irrelevante. A la fecha de caducidad no le importan los lectores. Hará ping al propietario en la fecha prevista a pesar de todo.

Las traducciones se quedan atrás

La fuente en inglés se actualizó el 10 de febrero. Las traducciones al francés, alemán y japonés están ahora atrasadas. Pero la fecha de caducidad de esas versiones traducidas no es hasta mayo. Durante tres meses, los equipos no ingleses están leyendo contenidos obsoletos y no lo saben.

Los lectores señalan los problemas

Un lector deja un comentario: "El paso 3 ya no funciona, la bandera CLI quedó obsoleta". Ese comentario se queda ahí. Aún faltan semanas para que caduque. Es posible que la siguiente persona que lea el documento no vea el comentario. La siguiente definitivamente no lo hará.

La caducidad es un punto de control programado. Estos son eventos no programados. La brecha entre ambos es donde la documentación obsoleta hace más daño.

Frescura: supervisión continua

La puntuación de la frescura llena el vacío que dejan las fechas de caducidad. En lugar de comprobar la salud de un documento una vez cada 90 días, la frescura realiza un seguimiento continuo. Cada día, en segundo plano, sin que nadie tenga que hacer nada.

Así es como funciona en Rasepi:

Cada documento obtiene una puntuación de frescura en vivo de 0 a 100, calculada a partir de múltiples señales:

Señal	Lo que detecta	Por qué es importante
Salud de los enlaces	URLs rotas, redirigidas o inalcanzables	Los enlaces rotos erosionan la confianza y hacen perder tiempo
Estado de la revisión	Si el documento ha sido revisado en la fecha prevista	La comprobación básica de la rendición de cuentas
Tendencias de lectura: si alguien lo está leyendo realmente. Una lectura baja sugiere que el documento puede ser irrelevante.
La fecha de la última modificación del documento en comparación con el contenido relacionado detecta la desviación con respecto a la base de conocimientos circundante.
Alineación de las traducciones: si todas las versiones lingüísticas están actualizadas. Las traducciones obsoletas significan que los equipos de otros mercados trabajan con información antigua.
Banderas de los lectores: si los lectores han informado de algún problema.
Referencias cruzadas: si los documentos a los que enlaza están también obsoletos.

Cada señal contribuye a la puntuación global. Un documento puede perder puntos de frescura por un enlace roto hoy, aunque su fecha de revisión no sea hasta dentro de semanas. De eso se trata.

Cómo funcionan las dos juntas

La caducidad y la frescura no son enfoques contrapuestos. Son capas complementarias:

Las fechas de caducidad son la capa de gobernanza. Crean una cadencia regular de revisión humana. Alguien tiene que mirar este documento en un calendario y confirmar que sigue siendo exacto. Esto capta las cosas que la automatización no puede: si el contenido sigue siendo correcto, si el asesoramiento sigue siendo sólido, si el proceso que describe sigue reflejando la realidad.

La puntuación de frescura es la capa de supervisión. Lo capta todo entre las fechas de revisión: los enlaces rotos, la deriva de la traducción, los documentos abandonados, la decadencia contextual que se produce cuando el mundo se mueve y un documento no.

Juntos crean un sistema en el que:

Cada documento es revisado por un humano según un calendario regular (caducidad)
Entre las revisiones, las señales automatizadas detectan los problemas a medida que se producen (frescura)
Ambos sistemas alimentan una única puntuación de confianza que todos pueden ver
Esa puntuación afecta a la clasificación del documento en las búsquedas y a si las herramientas de IA lo utilizan como fuente

El impacto de la puntuación

Aquí es donde la cosa se pone práctica. En Rasepi, la puntuación de frescura de un documento afecta directamente a su visibilidad:

Puntuación 80-100: Visibilidad total. Aparece normalmente en los resultados de búsqueda. Elegible como fuente para respuestas de IA. Sin banderas.
Puntuación 50-79:** Visibilidad reducida. Aparece en la búsqueda con un indicador de caducidad. Las herramientas de IA pueden despriorizarla como fuente. Se notifica al propietario.
Puntuación inferior a 50:** Señalada. Empujado hacia abajo en los resultados de búsqueda de manera significativa. Excluida por completo de las respuestas de la IA. El propietario recibe una notificación urgente.

Esto crea un bucle de retroalimentación. Cuando la puntuación de un documento desciende, el propietario se ve empujado a arreglarlo, no porque haya llegado una fecha arbitraria, sino porque algo ha cambiado realmente. El enlace roto, la traducción obsoleta, la disminución de lectores, son señales reales que exigen atención ahora, no dentro de seis semanas.

Un ejemplo práctico

Recorramos un escenario:

1 de marzo: Su "Libro de jugadas de respuesta a incidentes" obtiene una puntuación de 92. Fue revisado hace dos semanas, todos los enlaces son válidos, el número de lectores es alto y las versiones en los cuatro idiomas están actualizadas.

8 de marzo: Alguien reestructura la página de estado de ingeniería. Tres URL del libro de jugadas ahora redirigen. La puntuación de frescura baja a 78. El propietario recibe una notificación: "3 enlaces rotos detectados".

10 de marzo: El propietario arregla los enlaces. La puntuación repunta a 89.

15 de marzo: La versión inglesa se actualiza con una nueva ruta de escalada. Las traducciones al francés y al alemán se han quedado obsoletas (desajuste del hash del contenido). La puntuación baja a 74.

17 de marzo: Se actualizan las traducciones. La puntuación vuelve a 91.

20 de marzo: Los datos de audiencia muestran que no se ha accedido a la versión japonesa en 30 días. La puntuación baja a 86. Una señal sutil, pero rastreada.

1 de abril: Llega la fecha prevista para la revisión. El propietario revisa el contenido, confirma que es correcto y amplía la caducidad hasta el 1 de julio. La puntuación se mantiene en 86 porque la señal de lectores sigue presente.

En ningún momento el equipo esperó a una fecha de revisión para detectar un problema. El sistema de frescura señaló los problemas en cuestión de días. La fecha de revisión proporcionó el punto de control de gobernanza. Ambas capas hacen su trabajo.

Por qué "fijar una fecha de revisión" ya no es suficiente

Hace cinco años, las fechas de caducidad podrían haber sido suficientes. La documentación era leída por la gente, y la gente puede ejercer su juicio. Si un documento parecía un poco raro, preguntaban por ahí.

Hoy en día, la documentación es infraestructura. Alimenta las herramientas de IA, la automatización de la incorporación, los sistemas de cumplimiento y los motores de búsqueda que ofrecen resultados sin contexto. Estos sistemas no ejercen un juicio. Consumen el contenido tal cual y lo redistribuyen a escala.

Un documento con enlaces rotos y traducciones obsoletas al que aún le quedan tres semanas para su fecha de revisión puede hacer mucho daño en esas tres semanas, sobre todo si un asistente de IA está sirviendo con confianza respuestas basadas en él.

Las fechas de caducidad son el enfoque mínimo viable para la gobernanza de la documentación. La puntuación de la frescura es lo que necesita cuando la documentación es consumida por sistemas que no pueden pensar por sí mismos.

Para empezar

Si ya tiene fechas de caducidad en sus documentos (bien por usted, en serio, la mayoría de los equipos ni siquiera hacen eso), aquí tiene cómo poner capas de frescura:

Inicie el seguimiento de enlaces. Realice una comprobación de enlaces rotos en sus 50 documentos principales. El número probablemente le sorprenderá.
Compruebe la alineación de las traducciones. Si tiene documentos multilingües, compare las fechas de última edición entre el documento original y las traducciones. ¿Cuántas llevan más de un mes de retraso?
Mire el número de lectores. ¿Qué documentos tienen un tráfico nulo? ¿Siguen siendo necesarios o deberían archivarse?
Hable con su equipo de IA. Si tiene un asistente interno de IA, pregúntele de qué documentos se abastece. A continuación, compruebe la frescura de esos documentos.

Probablemente descubrirá que sus documentos técnicamente no caducados tienen muchos problemas que las fechas de caducidad nunca detectarán.

Las fechas de caducidad le dicen si alguien ha revisado un documento recientemente. La frescura le dice si el documento está realmente sano en este momento. Una es un acontecimiento del calendario. El otro es una señal viva.

Necesita ambas. Pero si sólo tiene fechas de caducidad, está volando a ciegas entre los puntos de control.

Un documento no se vuelve rancio en su fecha de revisión. Se queda obsoleto en el momento en que algo cambia y nadie se da cuenta. La puntuación de la frescura se da cuenta.

Rasepi combina las fechas de caducidad obligatorias con la supervisión continua de la frescura. Cada documento gana su puntuación de confianza, o la pierde, en tiempo real. Sin esperas, sin puntos ciegos, sin sorpresas en el momento de la revisión.

Vea cómo funciona la puntuación de frescura →

Esta es la segunda parte de una serie de dos partes. Si aún no la ha leído, empiece por [Parte 1: La métrica que su equipo no está siguiendo](/es/blog/why-freshness-matters-more- than-ever/).

Frescura del contenido, Parte 1: La métrica que su equipo no está controlando

2026-03-16T00:00:00Z

Hay un momento que todo equipo de ingeniería ha experimentado. Alguien encuentra un documento en la wiki interna, sigue las instrucciones y algo se rompe. Envían un mensaje al canal: "¿Esto sigue siendo exacto?" Nadie lo sabe. La persona que lo escribió se fue hace ocho meses. El documento dice que se editó por última vez en 2024.

Este es el problema de la frescura. Y está empeorando.

El antiguo contrato se está rompiendo

Durante mucho tiempo, la documentación tenía un contrato implícito: alguien la escribe, todo el mundo confía en ella y, de vez en cuando, alguien la actualiza. Tal vez. Ese contrato funcionaba, a duras penas, cuando la documentación era consumida únicamente por personas que podían aplicar su criterio. Si una guía de configuración parecía un poco fuera de lugar, un ingeniero superior se limitaba a adaptarla sobre la marcha.

Pero ese mundo se acabó. Hoy su documentación no sólo es leída por humanos. Es consumida por herramientas de IA, chatbots internos, automatización de la incorporación y sistemas de búsqueda que tratan cada palabra como una verdad equivalente. Un asistente de IA no entrecierra los ojos ante un documento y piensa "hmm, esto parece un poco anticuado", sino que lee el texto, lo procesa como un hecho y lo sirve con plena confianza.

Documentación anticuada más IA equivale a respuestas erróneas con total confianza a escala.

Lo que realmente significa frescura

La frescura no es sólo "cuándo se editó esto por última vez". Un documento podría haber sido editado ayer y seguir haciendo referencia a una API obsoleta. La verdadera frescura es una señal compuesta:

Estado de revisión. ¿Alguien ha confirmado explícitamente que sigue siendo correcto?
Salud de los enlaces: ¿se siguen resolviendo las URL del documento?
Lectores. ¿Alguien está usando esto realmente, o ha sido abandonado?
Deriva contextual: ¿Han cambiado los documentos relacionados mientras que éste sigue igual?
Alineación de las traducciones.** Si existe en cinco idiomas, ¿están todos actualizados?
Señales de la comunidad.** ¿Los lectores lo han marcado como obsoleto?

Cada una de ellas le dice algo diferente. Juntos, le dan una puntuación de confianza: un único número que representa el grado de confianza que debe depositar en un contenido en este momento.

Por qué esto importa ahora, concretamente

Tres cosas han convergido para hacer que la frescura sea urgente:

1. La IA está consumiendo su base de conocimientos

Tanto si ha desplegado un sistema RAG interno, como si utiliza Copilot en su IDE o tiene un asistente de IA que responde a las preguntas de sus documentos, la calidad del material de origen determina directamente la calidad del resultado. Basura dentro, basura fuera nunca ha sido tan literal.

Cuando un desarrollador pregunta a su asistente de IA "¿cómo despliego en staging?" y éste le responde utilizando un runbook de hace dos años que hace referencia a una infraestructura que usted ya ha migrado, el coste no es sólo una respuesta errónea. Es la pérdida de confianza en todo el sistema.

2. Los equipos están más distribuidos que nunca

Un equipo en Berlín, otro en São Paulo, un tercero en Tokio. Todos leyendo la misma documentación, a menudo en idiomas diferentes. Cuando la fuente en inglés se queda obsoleta, todas las traducciones construidas sobre ella se quedan obsoletas también, pero nadie se da cuenta porque las traducciones se mantienen por separado, si es que se mantienen.

3. Aumenta la presión del cumplimiento y la auditoría

Las industrias reguladas están empezando a preguntar: "¿Puede demostrar que esta documentación estaba actualizada en el momento en que se hizo referencia a ella?". Si su respuesta es "bueno, probablemente alguien la comprobó", eso no se sostendrá.

Cómo es un enfoque que da prioridad a la frescura

La idea central es simple: cada documento debe ganarse continuamente el derecho a ser fiable.

Esto significa

Fechas de revisión obligatorias. Cada documento tiene una fecha de caducidad cuando se crea. Sin excepciones. Cuando llega la fecha, se notifica al propietario y el documento queda marcado hasta que alguien lo vuelva a aprobar explícitamente.
Vigilancia automatizada de la salud. En segundo plano, el sistema comprueba continuamente si hay enlaces rotos, tendencias de lectores y cambios contextuales. Estas señales alimentan una puntuación en vivo que se actualiza sin que nadie tenga que hacer nada.
La frescura afecta a la visibilidad. Éste es el mecanismo clave. Un documento con una puntuación alta sube a la parte superior de los resultados de búsqueda y es elegible para ser utilizado como fuente de respuestas de la IA. Un documento con una puntuación baja desciende en la clasificación. Si cae por debajo de un umbral, queda totalmente excluido de las respuestas de la IA.
Transparencia. Todo el mundo puede ver por qué un documento obtuvo la puntuación que obtuvo. Enlaces rotos, revisión atrasada, escasa lectura, las señales son visibles, no están ocultas en un informe backend que nadie lee.

El coste de no hacer nada

Esto es lo que ocurre cuando no se hace un seguimiento de la frescura:

Los nuevos contratados siguen documentos de incorporación obsoletos y pasan su primera semana confundidos
Las herramientas de IA ofrecen respuestas erróneas y nadie entiende por qué
Los documentos de cumplimiento se quedan obsoletos y crean riesgos de auditoría.
Las traducciones se desincronizan y los equipos de distintas regiones trabajan a partir de versiones diferentes de la realidad
Los ingenieros dejan de confiar por completo en la wiki y recurren a los mensajes de Slack, lo que crea su propio silo de conocimiento

El coste compuesto de la documentación obsoleta es enorme, pero es invisible hasta que algo se rompe.

Un punto de partida práctico

No necesita revisarlo todo a la vez. Empiece por esto:

Analice sus 20 documentos más leídos. ¿Cuándo se revisaron por última vez? ¿Siguen siendo válidos los enlaces? ¿Sigue siendo preciso el contenido?
Fije fechas de revisión. Aunque no haga nada más, poner una fecha de "revisión por" en cada documento crea responsabilidad.
**Si dispone de un asistente interno de inteligencia artificial, compruebe de qué documentos se nutre. ¿Están actualizados esos documentos?
**Ponga la puntuación donde la gente pueda verla, junto al título del documento, en los resultados de búsqueda, en la barra lateral. La visibilidad crea presión para mantenerla.

La frescura de la documentación no es una característica. Es un cambio fundamental en la forma en que pensamos sobre el conocimiento organizativo. En un mundo en el que las herramientas de IA consumen y redistribuyen su documentación a escala, la cuestión no es si puede permitirse preocuparse por la frescura. Es si puede permitirse no hacerlo.

Cada documento debería tener que demostrar que aún merece la pena confiar en él. No una vez. Continuamente.

Eso es lo que estamos construyendo en Rasepi. Una plataforma donde la frescura no es una ocurrencia tardía. Es la base sobre la que se construye todo lo demás. Aplicación de revisiones, puntuación de salud en vivo, búsqueda ponderada por frescura y respuestas de IA que sólo utilizan fuentes en las que puede confiar.

Vea cómo funciona →

Esta es la Parte 1 de una serie de dos partes. En Parte 2: Más allá de las fechas de caducidad, exploramos cómo el control continuo de la frescura llena las lagunas que dejan abiertas las fechas de revisión.

Enseñe a su IA a ignorar la documentación obsoleta

2026-03-12T00:00:00Z

Esto es lo que ocurre cuando despliega un asistente de IA sobre su base de conocimientos interna:

Un nuevo ingeniero pregunta: "¿Cómo configuro el entorno de ensayo?".

La IA busca en su documentación, encuentra tres documentos relevantes, sintetiza una respuesta y la presenta con confianza. El ingeniero sigue las instrucciones. Los dos primeros pasos funcionan. El paso tres hace referencia a una herramienta CLI que quedó obsoleta hace seis meses. El paso cuatro describe una configuración de infraestructura que fue sustituida durante una migración que nadie documentó.

El ingeniero está atascado. Envían un mensaje al canal del equipo. Alguien dice: "Oh, ese documento es muy antiguo". La IA no lo sabía. No puede saberlo. Simplemente buscó todo lo que encontró y lo presentó como verdad.

Este es el comportamiento por defecto de cada sistema RAG, cada herramienta de búsqueda de IA y cada asistente impulsado por LLM que haya utilizado alguna vez en documentos internos. Lo buscan todo. No discriminan. No distinguen lo fresco de lo rancio.

Y está destruyendo la confianza en las herramientas de IA más rápido de lo que esas herramientas pueden construirla.

Por qué los asistentes de IA son ciegos a la calidad

Los grandes modelos lingüísticos y los sistemas de generación aumentada por recuperación (RAG) funcionan encontrando texto que sea semánticamente relevante para una consulta y, a continuación, utilizando ese texto para generar una respuesta. La concordancia de relevancia suele ser excelente. La búsqueda vectorial y las incrustaciones son realmente buenas a la hora de encontrar contenidos relacionados con una pregunta.

Pero relevancia no es lo mismo que fiabilidad.

Un documento escrito en 2023 sobre su proceso de despliegue de Kubernetes es muy relevante para la pregunta "¿cómo despliego en producción?" También es completamente erróneo si usted migró a una plataforma diferente en 2024. La IA ve texto relevante. No ve un documento que está 18 meses desfasado con enlaces rotos y cero lectores.

La mayoría de los sistemas de IA tienen exactamente una señal de clasificación: semejanza semántica con la consulta. Eso es todo. No comprueban:

¿Cuándo se revisó este documento por última vez?
¿Siguen siendo válidos los enlaces que contiene?
¿Hay alguien leyendo realmente este documento?
¿Han marcado los lectores el contenido como obsoleto?
¿Se trata de un borrador, de una página archivada o de un documento actual?
Si existe en varios idiomas, ¿están actualizadas las traducciones?

Sin estas señales, la IA está haciendo una concordancia de palabras clave con pasos adicionales. Un cotejo de palabras clave impresionante, sí, pero fundamentalmente incapaz de decirle si la respuesta que está dando se basa en un contenido en el que puede confiar.

El problema de la confianza

Esto no sería tan peligroso si las herramientas de IA presentaran respuestas inciertas con las advertencias adecuadas. Pero no lo hacen. No es así como funcionan las LLM. Generan textos fluidos y seguros independientemente de si el material fuente es actual o antiguo.

Un humano que lea un artículo de wiki podría notar que parece anticuado. El diseño de la página es antiguo. Las capturas de pantalla muestran una interfaz de usuario que ya no existe. Hay un comentario al final que dice "esto está anticuado". Un humano puede aplicar su criterio.

Una IA no puede. Lee el texto, lo procesa como equivalente a cualquier otro texto y genera una respuesta que suena autoritaria. El usuario, especialmente un recién contratado que no sabe cómo es el proceso actual, no tiene motivos para dudar de ella.

Cuanta más confianza suene la IA, más daño hace el material de origen obsoleto.

Lo que la IA realmente necesita

Para que un asistente de IA dé respuestas fiables a partir de su base de conocimientos, necesita algo más que texto e incrustaciones. Necesita metadatos que le digan qué documentos merece la pena utilizar como fuentes. Concretamente:

1. Puntuación de frescura

Una señal numérica que representa la salud de un documento en este momento. No cuándo se editó por última vez, eso es sólo una entrada. Una verdadera puntuación de frescura combina el estado de revisión, la salud de los enlaces, el número de lectores, la alineación de la traducción y la deriva contextual en un único número.

Cuando un documento obtiene una puntuación por encima de un umbral (digamos, 70 sobre 100), es apto para ser utilizado como fuente para las respuestas de la IA. Por debajo de ese umbral, queda excluido. No hay excepciones.

Este único mecanismo elimina la clase más peligrosa de errores de IA: las respuestas erróneas basadas en fuentes obsoletas.

2. Estado de caducidad

¿Este documento se encuentra actualmente dentro de su plazo de revisión o ha caducado sin haber sido reaprobado? Un documento caducado debe ser fuertemente despriorizado o excluido por completo, independientemente de lo relevante que pueda ser su contenido para la consulta.

En Rasepi, los documentos caducados se marcan y su puntuación de frescura desciende automáticamente. Un sistema de IA que consulte la base de conocimientos puede ver este estado y actuar en consecuencia.

3. Etiquetas de clasificación

No todos los documentos sirven para lo mismo. Un borrador no debería utilizarse como fuente. Un documento archivado no debería aparecer en las respuestas de AI. Un documento interno no debe aparecer en las consultas de herramientas externas.

Las etiquetas de clasificación proporcionan a la IA el contexto sobre el tipo de documento que está consultando:

Publicado. Actual, aprobado, seguro de usar
Borrador: trabajo en curso, no debe citarse.
En revisión.** Expirado, en espera de reaprobación
Archivado. Ya no activo, guardado sólo como referencia
Interna / Externa. Controla el alcance de la visibilidad

Cuando un asistente de IA procesa una consulta, puede filtrar por clasificación antes incluso de fijarse en la relevancia del contenido. Un borrador de documento que coincida perfectamente con la consulta nunca debe ser servido como respuesta.

4. Señales a nivel de idioma

Si su base de conocimientos es multilingüe, la IA necesita saber si la versión de la que está extrayendo la información es actual. Una traducción al francés que lleva tres meses de retraso con respecto a la fuente en inglés es técnicamente relevante en francés, pero la información podría estar desfasada.

Rasepi realiza un seguimiento de la actualidad a nivel de idioma. Cada traducción tiene su propia puntuación basada en si sus bloques de origen han cambiado desde la última actualización de la traducción. Una IA que consulte la base de conocimientos en francés puede ver que la versión francesa de un documento está obsoleta y, o bien:

Volver a la fuente inglesa (que es actual)
Incluir una advertencia de que la versión francesa puede estar anticuada
Excluir el documento por completo

5. Señales de lectura

Si varios lectores han marcado un documento como obsoleto, esa señal debería reducir el peso del documento en las respuestas de la IA. Las señales de calidad crowdsourced son ruidosas, pero valiosas, especialmente cuando se combinan con otras métricas de frescura.

Cómo funciona en la práctica

Veamos qué ocurre cuando un asistente de IA consulta una base de conocimientos Rasepi:

Consulta: "¿Cuál es nuestro proceso para gestionar un incidente P1 a las 2 de la madrugada?"

Paso 1: Recuperación con filtrado. El sistema busca documentos semánticamente relevantes. Antes de clasificarlos, los filtra:

Los documentos con una puntuación de frescura inferior al umbral
Documentos caducados que no han sido reaprobados
Borradores y contenidos archivados
Documentos cuya versión lingüística esté obsoleta (si la consulta está en una lengua no primaria)

Paso 2: Clasificación ponderada en función de la frescura. Entre los documentos restantes, los que obtienen puntuaciones de frescura más altas se clasifican mejor. Un documento con una puntuación de 94 supera a otro con una puntuación de 72, incluso si el documento con una puntuación de 72 tiene una similitud semántica ligeramente superior.

**Paso 3: Generación de respuestas La IA genera una respuesta a partir de las fuentes filtradas y clasificadas según su frescura. Cada fuente se cita con su puntuación de frescura visible.

**Paso 4: Advertencias de caducidad: si la mejor fuente disponible tiene una puntuación de frescura límite, la IA incluye una advertencia: "Nota: la fuente principal de esta respuesta se revisó por última vez hace 60 días. Es posible que desee verificarla con el equipo".

Compare esto con el comportamiento por defecto: encontrar el texto relevante, generar una respuesta segura, esperar lo mejor.

Qué ocurre cuando no se hace esto

Las consecuencias de que los sistemas de IA funcionen con bases de conocimientos sin filtrar son predecibles y costosas:

Confusión de los nuevos empleados. El caso de uso más común de la IA para los documentos internos es la incorporación. Los recién contratados, por definición, no saben lo que es actual y lo que es obsoleto. Confían en la IA. La IA confía en todo. Los documentos obsoletos se sirven con confianza.

Exposición al cumplimiento. Si su asistente de IA ofrece orientación sobre procesos normativos utilizando documentos obsoletos, el asesoramiento no sólo puede ser erróneo, sino que puede incumplir la normativa. "La IA me lo dijo" no se sostiene en una auditoría.

Erosión de la confianza. Cada vez que la IA da una respuesta errónea, los usuarios confían un poco menos en ella. Después de tres o cuatro malas experiencias, dejan de utilizarla. La inversión en herramientas de IA no aporta ningún valor porque el contenido subyacente no era digno de confianza.

Conocimiento en la sombra. Cuando la gente pierde la confianza en la base de conocimientos oficial (y en la IA construida sobre ella), crea la suya propia: Mensajes de Slack, notas personales, conocimiento tribal compartido en reuniones. La fragmentación que se suponía que la wiki debía evitar se produce de todos modos, sólo que de forma diferente.

La solución está en la fuente, no en el modelo

Existe la tentación de solucionar esto en la capa de IA: mejores avisos, canalizaciones RAG más sofisticadas, modelos afinados que puedan detectar de algún modo el estancamiento a partir del texto únicamente. Este es el enfoque equivocado.

La solución está en la fuente. Si sus documentos llevan metadatos ricos y precisos sobre su estado actual (puntuación de frescura, estado de caducidad, clasificación, alineación lingüística, señales del lector), entonces cualquier sistema de IA puede utilizar esos metadatos para tomar mejores decisiones. No necesita un modelo más inteligente. Necesita documentos más inteligentes.

Esto es lo que proporciona Rasepi:

Cada documento tiene una puntuación de frescura en vivo que se actualiza continuamente en función de la salud de los enlaces, el número de lectores, el estado de revisión, etc.
Cada documento tiene una fecha de caducidad que activa la revisión cuando llega
Cada documento tiene una clasificación (publicado, borrador, en revisión, archivado)
Cada versión lingüística tiene su propia señal de frescura para que las traducciones obsoletas se detecten de forma independiente
Los indicadores de lectura y el seguimiento de referencias cruzadas añaden señales de calidad adicionales

Cuando un sistema de IA consulta la base de conocimientos de Rasepi, todos estos metadatos están disponibles. La IA no tiene que adivinar si un documento es fiable. El documento se lo dice.

Un punto de partida práctico

Si hoy tiene un asistente de IA funcionando en su base de conocimientos, puede empezar a evaluar el problema en 30 minutos:

Pregunte a su asistente de IA 10 preguntas de las que conozca las respuestas. Observe qué respuestas utilizan fuentes obsoletas. Probablemente encontrará que al menos 2 ó 3 de cada 10 se basan en contenidos obsoletos.
Compruebe los documentos fuente. Para cada respuesta que le haya dado la IA, mire el documento fuente. ¿Cuándo se revisó por última vez? ¿Son válidos los enlaces? ¿Confiaría en él si lo leyera usted mismo?
Busque el peor de los casos. Encuentre su documento más antiguo y descuidado que aún aparezca en los resultados de búsqueda. Formule a la IA una pregunta que lo haga aparecer. ¿La IA lo utiliza? Es casi seguro que sí.
Estime el impacto. ¿Cuántas consultas al día gestiona su asistente de IA? Si el 20-30% de las respuestas se basan en contenidos obsoletos, ¿cuál es el coste en términos de pérdida de tiempo, decisiones equivocadas y pérdida de confianza?

Los asistentes de IA sólo son tan buenos como el contenido sobre el que se basan. Ahora mismo, la mayoría de ellos tratan todos los documentos de su base de conocimientos como igualmente válidos. Lo buscan todo, el documento que se revisó ayer y el que nadie ha tocado en dos años, y lo presentan todo con la misma confianza.

Eso no es un problema de modelo. Es un problema de calidad de los datos. Y la solución es sencilla: proporcione a sus documentos metadatos que indiquen a las herramientas de IA en qué deben confiar.

Su asistente de IA no debería dar por segura una respuesta procedente de un documento que nadie ha revisado en 18 meses. Con las señales adecuadas, no lo hará.

Rasepi hace que cada documento lleve su propia puntuación de confianza: frescura, estado de caducidad, clasificación, alineación lingüística. Las herramientas de IA consultan la base de conocimientos y obtienen no sólo el contenido, sino el contexto. Las fuentes fiables salen a la superficie. Las obsoletas, no. Así es como debería funcionar la documentación potenciada por la IA.

Vea cómo funciona Rasepi con las herramientas de IA →

Hablar con los documentos es mejor que leerlos

2026-03-10T00:00:00Z

Hay una razón por la que la gente dice "hablemos de ello" cuando algo es complejo.

Cuando intentamos comprender una idea nueva, resolver un problema o recordar un proceso bajo presión, la conversación suele resultar más fácil que la lectura. No porque leer sea malo. La lectura es una de las herramientas más poderosas que ha desarrollado el ser humano. Pero la lectura es una habilidad aprendida que se superpone a algo mucho más antiguo: el habla.

Somos habladores mucho antes que lectores.

Eso importa más de lo que la gente cree, sobre todo ahora que la mayor parte del conocimiento del mundo vive dentro de documentos, wikis, PDF y largas páginas internas que nadie quiere abrir a menos que sea absolutamente necesario.

La lectura se aprende. La conversación es nativa.

Los seres humanos hablaron durante mucho tiempo antes de escribir nada. Los niños aprenden a comprender el lenguaje hablado de forma natural. La lectura requiere instrucción explícita, repetición y años de práctica.

Incluso para los adultos altamente alfabetizados, la lectura sigue siendo un acto más deliberado que escuchar o hablar. Requiere concentración visual, atención continua, memoria de trabajo e interpretación de la estructura de la página. Se descodifican símbolos, se analizan frases, se construye el contexto y se decide lo que importa.

La conversación funciona de forma diferente. Cuando la información se transmite de forma hablada e interactiva, el cerebro vive una experiencia diferente:

Se siente secuencial en lugar de visualmente abrumadora.
Proporciona información y aclaraciones inmediatas
Reduce la necesidad de escanear y filtrar grandes bloques de texto
Refleja la forma en que la gente pide ayuda en la vida real.

Este último punto es muy importante. Ante la incertidumbre, la mayoría de la gente no quiere leer instintivamente 1.500 palabras. Quieren preguntar: _"¿Qué hago ahora?

Hablar reduce la fricción cognitiva

Un documento es estático. Lo contiene todo a la vez.

Parece útil, y a menudo lo es. Pero también crea fricción. Una página llena de encabezamientos, llamadas, enlaces, notas, ejemplos y casos extremos obliga al lector a decidir qué ignorar. Eso es cognitivamente costoso.

Cuando se habla con un sistema de información, se suele obtener la experiencia opuesta: la relevancia primero, el detalle después.

Usted hace una pregunta. Obtiene una respuesta. Luego hace una pregunta de seguimiento.

Ese patrón de interacción reduce la sobrecarga mental de varias formas importantes:

1. Reduce el espacio del problema

Un documento completo presenta todo el panorama. Una conversación presenta el siguiente paso útil.

Cuando alguien pregunta: "¿Cómo incorporo a un nuevo ingeniero?", normalmente no quieren todo el manual inmediatamente. Quieren orientación. La conversación les permite empezar poco a poco y ampliar sólo cuando sea necesario.

2. Preserva la memoria de trabajo

Leer le obliga a retener varias cosas en la cabeza mientras busca la parte relevante. La interacción oral o conversacional externaliza ese esfuerzo. El sistema hace más del filtrado por usted.

3. Le resulta socialmente familiar

Los humanos estamos profundamente adaptados al intercambio de ida y vuelta. Preguntamos. Alguien responde. Afinamos. Ellos aclaran. Ese bucle es una de las formas de aprendizaje más antiguas que tenemos.

Incluso cuando el "alguien" es un sistema, la estructura sigue pareciendo natural.

Leer no es pasivo. Esa es exactamente la cuestión.

Una de las razones por las que hablar puede parecer más fácil es que leer no es tan fácil como la gente supone. Los lectores expertos hacen que parezca que no requiere esfuerzo, pero el proceso es muy activo.

Para leer bien, tiene que hacerlo:

identificar la estructura
deducir la importancia
resolver la ambigüedad
mantener el contexto en la memoria
conectar una sección con otra
decidir cuándo hojear y cuándo ir más despacio

Eso es verdadero trabajo cognitivo.

En muchas situaciones, ese trabajo merece la pena. La lectura profunda ayuda con los matices, la precisión y la comprensión a largo plazo. Pero en otras situaciones, especialmente cuando alguien está cansado, estresado, sobrecargado o simplemente intenta desatascarse, hablar es a menudo la opción mentalmente más ligera.

Esto es especialmente cierto en el lugar de trabajo, donde la gente no suele acercarse a la documentación en condiciones ideales. Lo están:

a mitad de tarea
interrumpida
cambiando de contexto
intentando resolver algo rápidamente
a menudo ya ligeramente frustrado

En ese estado, el acceso conversacional a la información puede sentirse mucho mejor que el acceso a través de una página.

Hablar cambia la relación con la información

Aquí también hay una dimensión emocional.

Los documentos pueden parecer formales y distantes. Implican: lea todo esto, entiéndalo bien y no se pierda nada importante. Eso puede ser útil como material de referencia, pero también puede crear dudas.

La conversación se siente permisiva. Se puede ser vago. Puede preguntar mal. Puede admitir confusión. Puede decir: "En realidad no sé lo que estoy buscando, pero necesito lo de las solicitudes de acceso".

Eso importa porque la gente suele evitar la documentación no porque no les guste la información, sino porque les disgusta el esfuerzo y la incertidumbre que supone encontrar la parte adecuada.

Hablar reduce esa barrera.

Por qué esto importa ahora

Durante mucho tiempo, había que leer los documentos porque no existía una alternativa práctica. La búsqueda ayudó a la gente a encontrar páginas, pero no cambió el modelo de interacción. Aún había que abrir la página, escanearla y extraer lo que se necesitaba.

Eso está cambiando.

A medida que las interfaces se vuelven más conversacionales, la gente espera cada vez más que la información responda en lugar de simplemente existir. Quieren pedir lo que necesitan en un lenguaje sencillo y recibir algo adaptado al momento.

Esto no hace que la lectura sea obsoleta. Cambia su función.

La lectura se convierte en la capa profunda. La conversación se convierte en la capa de acceso.

Los mejores sistemas soportarán ambas:

hablar cuando necesite orientación o rapidez
leer cuando necesite profundidad, verificación o contexto completo

El riesgo de simplificar en exceso

Hay una advertencia importante: hablar con información sólo sienta mejor si las respuestas son fiables.

Si una interfaz conversacional da respuestas parciales, engañosas o demasiado seguras, la experiencia se vuelve peor que la lectura porque elimina la capacidad del usuario de inspeccionar directamente el material fuente.

Así que el futuro no es "sustituir todos los documentos por la voz". El futuro es dar a la gente una forma más humana de acceder a los documentos sin perder la profundidad y la precisión que proporciona el conocimiento escrito.

Ese equilibrio es importante. Conversar es más fácil, pero los documentos siguen teniendo la estructura duradera, el detalle y la responsabilidad que necesitan las organizaciones.

Una interfaz más humana para el conocimiento

El punto más profundo es sencillo: las personas no piensan de forma natural en páginas. Piensan en preguntas, historias, fragmentos y diálogo.

Nosotros preguntamos:

¿Qué significa esto?
¿Qué hago primero?
¿Cuál es la parte importante?
¿Puede explicarlo de otra manera?
¿Qué ha cambiado?

Son movimientos de conversación, no de lectura.

Así que cuando hablar con la información resulta mentalmente más fácil que leerla, no es un signo de pereza intelectual. Suele ser una señal de que la interfaz coincide con la forma en que el cerebro prefiere abordar la incertidumbre.

La lectura sigue siendo esencial. Pero como punto de entrada al conocimiento, la conversación a menudo se siente mejor porque está más cerca de lo que somos por naturaleza.

Primero no somos lectores. Primero somos habladores. Los sistemas de conocimiento más intuitivos lo recordarán.

Plataformas de documentación creadas para otra época

2026-03-08T00:00:00Z

Confluence y Notion no son malos productos. Eso hay que decirlo claramente desde el principio.

Tuvieron éxito por buenas razones. Confluence se convirtió en el hogar por defecto de la documentación interna en muchas empresas porque ofrecía a los equipos un lugar central para escribir, organizar y compartir conocimientos. Notion se ganó a la gente con flexibilidad, experiencias de escritura más limpias y una superficie de producto de sensación más moderna.

Ambas plataformas resolvieron problemas reales en la época para la que fueron construidas.

El problema ahora es que el mundo que las rodea ha cambiado más rápido que sus fundamentos.

Ya no estamos en un mundo en el que la documentación sólo necesita escribirse, almacenarse y buscarse. Estamos en un mundo en el que cada vez se espera más de la documentación:

legible por máquina
consciente de la frescura
segura para la recuperación mediante IA
lo suficientemente estructurada para la automatización
dinámico en todos los idiomas y para todos los públicos
continuamente fiable, no sólo disponible

Se trata de un listón diferente.

Se construyeron para un modelo de conocimiento anterior a la IA

Las plataformas de documentación tradicionales se diseñaron en torno a un supuesto simple: si la página existe y se puede buscar en ella, el problema está resuelto en su mayor parte.

Eso era suficientemente bueno cuando el usuario principal era un humano que abría un wiki, hojeaba la página y aplicaba su criterio. En ese modelo, el trabajo de la plataforma consistía en facilitar la autoría y la navegación.

La IA cambia la descripción del trabajo.

Ahora la plataforma no se limita a almacenar conocimientos para las personas. Está produciendo material fuente para sistemas que recuperan, clasifican, resumen y responden preguntas automáticamente.

Eso introduce nuevos requisitos que las arquitecturas anteriores no priorizaban:

¿Qué contenidos son fiables en este momento?
¿Qué páginas están obsoletas pero aún se pueden buscar?
¿Qué secciones han cambiado recientemente?
¿Qué versión lingüística es la actual?
¿Qué contenidos son borradores, están archivados, son específicos de una región o son poco fiables?
¿Qué documentos deberían excluirse por completo de las respuestas AI?

Una plataforma que no se haya construido en torno a estas preguntas tiene que adaptarlas. Eso siempre es más difícil que diseñar para ellas desde el principio.

La fuerza heredada se convierte en un lastre heredado

Los productos establecidos tienen ventajas: distribución, ecosistema, marca, familiaridad con el cliente, integraciones y equipos que saben cómo hacer envíos. Pero esas mismas fortalezas pueden ralentizar el cambio estructural.

¿Por qué? Porque las plataformas maduras conllevan compromisos.

Los tienen:

años de decisiones acumuladas sobre productos
enormes bases instaladas con flujos de trabajo existentes
expectativas en torno a la compatibilidad con versiones anteriores
plugins y extensiones que dependen de comportamientos antiguos
modelos de datos optimizados para los casos de uso de ayer

Cuando una plataforma como Confluence o Notion quiere añadir una capacidad realmente nueva, a menudo tiene que encajar esa capacidad alrededor del sistema existente en lugar de a través de él.

Ése es el reto de la incumbencia: no sólo está construyendo el futuro, sino que está arrastrando el pasado consigo.

Añadir funciones de IA no es lo mismo que convertirse en nativo de IA

Muchas plataformas establecidas están ahora superponiendo la IA. Resúmenes. Ayuda a la escritura. Mejoras en la búsqueda. Interfaces de preguntas y respuestas. Confluence cuenta con Atlassian Intelligence, Notion ha incorporado Notion AI y GitBook ha añadido AI-powered search. Se trata de funciones útiles. Algunas de ellas son buenas.

Pero hay una diferencia significativa entre:

añadir características de IA a un producto de documentación
construir un producto de documentación cuya arquitectura central asuma el consumo de IA desde el primer día

El primer enfoque suele dar lugar a funciones de asistencia en los bordes. El segundo cambia los cimientos.

Una plataforma de conocimiento nativa de la IA plantea preguntas de diseño diferentes desde el principio:

¿cómo deben estructurarse los documentos para que los sistemas puedan razonar sobre ellos con seguridad?
¿cómo debe representarse la confianza?
¿qué metadatos deben ser de primera clase y no opcionales?
¿cómo debe degradarse la visibilidad de los contenidos obsoletos?
¿cómo deben restringirse las respuestas cuando las fuentes subyacentes son débiles?

Se trata de cuestiones de arquitectura, no de características.

Las plataformas frescas tienen una ventaja temporal

Aquí es donde las plataformas más nuevas pueden ganar, al menos durante un tiempo.

Una plataforma nueva tiene la libertad de diseñar en torno a las limitaciones de hoy en lugar de los hábitos de ayer. No tiene que conservar una década de suposiciones sobre lo que es un documento o cómo debe comportarse un wiki. Puede tomar decisiones diferentes desde el principio:

tratar la frescura como un concepto de primera clase
hacer que la confianza en la fuente sea visible tanto para los humanos como para las máquinas
almacenar metadatos más ricos sobre el estado del contenido
integrar los flujos de trabajo multilingües en el modelo básico en lugar de añadirlos por añadidura
Decidir que la búsqueda y la recuperación mediante inteligencia artificial se clasifiquen en función de la confianza y no sólo de la relevancia.

Que la libertad importa.

En tecnología, los operadores tradicionales suelen ser más fuertes durante los periodos estables. Los nuevos competidores suelen ser más fuertes cuando el propio modelo está cambiando.

La era de la IA es uno de esos cambios.

Por qué esto es especialmente duro para Confluence

Confluence es potente, pero procede de una visión del mundo más antigua. Se construyó en torno a espacios de equipo, páginas, navegación jerárquica, y un modelo de empresa rico en plugins. Esas opciones tenían sentido. Siguen teniendo sentido para muchas organizaciones.

Pero también significan que el producto arrastra mucha complejidad. Las plataformas empresariales rara vez consiguen reinventarse limpiamente. Tienen que negociar con su propia historia.

Eso hace que la modernización sea más lenta. No imposible. Sólo más lenta.

Cuando los requisitos de la era de la inteligencia artificial exigen metadatos más limpios, un modelado de confianza más explícito o una gobernanza de contenidos más orientada a las opiniones, un sistema construido para ofrecer la máxima flexibilidad a través de años de ampliaciones puede tener dificultades para moverse de forma cohesionada.

Por qué esto es especialmente delicado para Notion

Notion tiene un problema diferente. Parece más nuevo, más ligero y más flexible. Pero la flexibilidad también puede jugar en su contra.

El punto fuerte de Notion es que casi cualquier cosa puede convertirse en una página, una base de datos, una nota, un documento ligero o un espacio de colaboración. Esa flexibilidad es estupenda para los equipos. Es menos genial cuando se necesitan garantías sólidas sobre el significado del contenido, el estado en que se encuentra y si debe ser utilizado como fuente de confianza por un sistema de IA.

Cuanto más libre sea una plataforma, más difícil será imponer una semántica fiable más adelante.

Los sistemas de IA prosperan con estructura, metadatos explícitos y señales de confianza. Los espacios de trabajo flexibles de uso general a menudo necesitan mucha interpretación antes de que su contenido sea seguro para ese tipo de uso.

Nada de esto significa que estén condenados

Sería un análisis perezoso decir que Confluence y Notion no pueden adaptarse. Por supuesto que pueden.

Cuentan con equipos inteligentes, importantes recursos y fuertes incentivos. Lanzarán más capacidades de IA. Mejorarán la recuperación, la ayuda a la autoría, los resúmenes, la gobernanza y los flujos de trabajo estructurados. Con el tiempo, es posible que acorten muchas distancias.

Pero el momento es importante.

Cuando se produce un cambio como éste, la ventaja suele pertenecer a quien esté dispuesto a reconstruir los supuestos más rápidamente. Las plataformas más nuevas pueden moverse con más coherencia porque no se están adaptando tanto. Eso les da una ventana.

Puede que no sea una ventana permanente. Pero es real.

La siguiente fase de las plataformas de documentación

Es probable que la próxima generación de herramientas de documentación se juzgue menos por lo bien que permiten a la gente escribir páginas y más por lo bien que gestionan el conocimiento como un sistema de confianza.

Eso significa que los ganadores probablemente harán bien cinco cosas:

Modelarán la confianza de forma explícita.
Distinguirán el conocimiento actual del conocimiento obsoleto.
Manejarán la recuperación de la IA como una superficie central del producto, no como un añadido.
Soportarán el conocimiento multilingüe y específico de la audiencia sin fragmentación.
Proporcionarán a los equipos un mayor control sobre qué información se muestra, a quién y en qué condiciones.

Se trata de una categoría diferente a la del wiki clásico.

Por qué importan los nuevos comienzos

Hay momentos en el software en los que un producto de hoja en blanco tiene ventaja no porque los titulares sean incompetentes, sino porque la historia es cara.

Este es uno de esos momentos.

Una nueva plataforma puede decidir, desde el primer día, que los documentos no son sólo páginas. Son fuentes activas para humanos, agentes, sistemas de búsqueda y asistentes de IA. Esa asunción lo cambia todo aguas abajo.

Confluence y Notion pueden llegar hasta ahí. Pero el camino es más largo porque tienen que transformar sistemas que estaban optimizados para otra época.

Esa transformación lleva tiempo. Mientras tanto, las plataformas más nuevas tienen margen para definir cómo debe ser una infraestructura del conocimiento moderna.

La mayor ventaja de una plataforma nueva no es la novedad. Es liberarse de las viejas suposiciones justo en el momento en que esas suposiciones dejan de funcionar.

Este es un artículo de perspectiva. Las afirmaciones sobre los productos de la competencia se basan en la documentación y los anuncios de productos disponibles públicamente en marzo de 2026. Respetamos sinceramente tanto a Confluence como a Notion: son productos excelentes que prestan un buen servicio a millones de equipos.

Dentro de la arquitectura Rasepi: Plugins, Action Guards y Pipelines

2026-03-06T00:00:00Z

La mayoría de las plataformas de documentación hablan de "extensibilidad" como las aerolíneas hablan de "espacio para las piernas". Técnicamente presente, prácticamente decepcionante. Yo quería que la arquitectura de Rasepi fuera realmente extensible sin volverse impredecible, así que construimos tres sistemas interconectados: plugins para la capacidad, guardias de acción para el control, y pipelines para la ejecución determinista.

Este artículo explica cómo funciona cada uno de ellos en nuestra base de código real.

Arquitectura Rasepi: Plugins, guardias y tuberías trabajando juntos](/es/blog/img/architecture-pipeline.svg)

El sistema de plugins: modular por diseño

Cada plugin en Rasepi implementa IPluginModule, una única interfaz que declara qué es el plugin, qué servicios necesita y qué rutas expone:

public interface IPluginModule
{
    PluginManifest Manifest { get; }
    void RegisterServices(IServiceCollection services);
    void MapRoutes(IEndpointRouteBuilder routes);
}

El PluginManifest es puro dato. Describe el plugin sin ejecutar nada:

public sealed class PluginManifest
{
    public required string Id { get; init; }
    public required string Name { get; init; }
    public required string Version { get; init; }
    public string Description { get; init; }
    public string Category { get; init; }
    public IReadOnlyDictionary<string, string> UiContributions { get; init; }
    public bool HasSettings { get; init; }
    public bool HasEndpoints { get; init; }
    public IReadOnlyList<string> Dependencies { get; init; }
}

Fíjese en UiContributions. Ese diccionario mapea puntos de extensión del frontend a nombres de componentes, de modo que el frontend Vue sabe qué componentes de interfaz de usuario aporta cada plugin (un botón de la barra de herramientas, un panel de la barra lateral, una página de configuración).

El registro es una línea por plugin

Al inicio, registramos los plugins a través de una API fluida:

var pluginRegistry = new PluginRegistry();

pluginRegistry
    .AddPlugin<WorkflowPluginModule>(builder.Services)
    .AddPlugin<RulesPluginModule>(builder.Services)
    .AddPlugin<RetentionPluginModule>(builder.Services)
    .AddPlugin<ClassificationPluginModule>(builder.Services);

Cada llamada instancia el módulo, lo almacena en el registro y llama a RegisterServices() para cablear sus dependencias. Tras la compilación de la aplicación, una única línea asigna todas las rutas de los plugins:

app.MapPluginRoutes(pluginRegistry);

Bajo el capó, cada plugin obtiene un grupo de rutas con alcance en /api/plugins/{pluginId}/ con autorización aplicada automáticamente.

Ejemplo real: el plugin Workflow

He aquí el aspecto de un plugin real, el módulo Workflow & Approvals:

public sealed class WorkflowPluginModule : IPluginModule
{
    public const string PluginId = "workflow";

    public PluginManifest Manifest { get; } = new()
    {
        Id = PluginId,
        Name = "Workflow & Approvals",
        Version = "1.0.0",
        Description = "Adds approval workflows to entry publishing.",
        Category = "Workflow",
        HasSettings = true,
        HasEndpoints = true,
        UiContributions = new Dictionary<string, string>
        {
            ["entry.toolbar.publish"] = "WorkflowPublishButton",
            ["entry.sidebar.status"]  = "WorkflowStatusPanel",
            ["hub.admin.settings"]    = "WorkflowHubSettings",
        }
    };

    public void RegisterServices(IServiceCollection services)
    {
        services.AddScoped<IWorkflowService, WorkflowService>();
        services.AddScoped<IActionGuard, WorkflowPublishGuard>();
    }

    public void MapRoutes(IEndpointRouteBuilder routes)
    {
        WorkflowEndpoints.Map(routes);
    }
}

La plataforma central nunca hace referencia a WorkflowService o WorkflowPublishGuard directamente. Los descubre a través del contenedor DI. Esa es la clave del acoplamiento cero. La aplicación core nunca toca el código de los plugins.

Guardias de acción: la capa de control

Los plugins añaden capacidad. Los guardianes de acción deciden si esa capacidad, o cualquier acción del núcleo, tiene permiso para proceder. Son validadores síncronos que interceptan las operaciones antes de su ejecución.

Flujo de evaluación de guardias de acción](/es/blog/img/action-guard-flow.svg)

La interfaz es deliberadamente mínima:

public interface IActionGuard
{
    string PluginId { get; }
    string? ActionName { get; }  // null means guard ALL actions

    Task<ActionGuardResult> EvaluateAsync(
        ActionGuardContext context,
        IServiceProvider services,
        CancellationToken ct = default);
}

Cuando ActionName es null, la guardia se ejecuta para cada acción. Cuando se establece en algo como "Entry.Publish", sólo intercepta esa acción específica.

Los contratos de contexto y resultado

Cada guardia recibe un contexto tipificado con el nombre de la acción, el arrendatario, el usuario, la entidad y una bolsa de propiedades:

public sealed record ActionGuardContext(
    string ActionName,
    Guid TenantId,
    Guid UserId,
    Guid EntityId,
    IReadOnlyDictionary<string, object?> Properties)
{
    public T? Get<T>(string key) =>
        Properties.TryGetValue(key, out var v) && v is T typed
            ? typed : default;
}

Y cada guardia devuelve un resultado predecible: permitir, denegar o permitir-con-modificaciones:

public sealed record ActionGuardResult
{
    public bool IsAllowed { get; init; }
    public string? ReasonCode { get; init; }
    public string? Message { get; init; }
    public IReadOnlyDictionary<string, object?>? Modifications { get; init; }

    public static ActionGuardResult Allow() =>
        new() { IsAllowed = true };

    public static ActionGuardResult Deny(
        string reasonCode, string message) =>
        new() { IsAllowed = false, ReasonCode = reasonCode, Message = message };
}

El campo Modifications es importante. Un guardia puede aprobar una acción pero reescribir parte del contenido (por ejemplo, redactar secretos antes de publicarlos).

Nombres canónicos de las acciones

Definimos todas las acciones interceptables como constantes de cadena para que no haya ambigüedad sobre a qué puede apuntar un guardia:

public static class ActionNames
{
    public static class Entry
    {
        public const string Create  = "Entry.Create";
        public const string Save    = "Entry.Save";
        public const string Publish = "Entry.Publish";
        public const string Delete  = "Entry.Delete";
        public const string Archive = "Entry.Archive";
        public const string Renew   = "Entry.Renew";
    }

    public static class Hub
    {
        public const string Create = "Hub.Create";
        public const string Delete = "Hub.Delete";
        public const string TransferOwnership = "Hub.TransferOwnership";
    }

    public static class Translation
    {
        public const string Create  = "Translation.Create";
        public const string Publish = "Translation.Publish";
    }
}

Ejemplo real: bloquear la publicación sin aprobación

El complemento de flujo de trabajo registra un guardia que intercepta Entry.Publish:

public sealed class WorkflowPublishGuard : IActionGuard
{
    public string PluginId => WorkflowPluginModule.PluginId;
    public string? ActionName => ActionNames.Entry.Publish;

    public async Task<ActionGuardResult> EvaluateAsync(
        ActionGuardContext context,
        IServiceProvider services,
        CancellationToken ct = default)
    {
        var db = services.GetRequiredService<RasepiDbContext>();
        var entry = await db.Entries
            .AsNoTracking()
            .FirstOrDefaultAsync(e => e.Id == context.EntityId, ct);

        if (entry is null)
            return ActionGuardResult.Allow();

        var workflowService = services.GetRequiredService<IWorkflowService>();
        var check = await workflowService
            .CheckPublishAllowedAsync(entry.Id, entry.HubId);

        if (check.IsAllowed)
            return ActionGuardResult.Allow();

        return ActionGuardResult.Deny(
            "workflow.approval_required",
            check.Message ?? "Approval required before publishing.");
    }
}

La plataforma central no sabe nada acerca de los flujos de trabajo de aprobación. Simplemente llama a Entry.Publish a través de la tubería, y el guardia lo bloquea si el flujo de trabajo no se ha completado.

La canalización de acciones: donde todo converge

El ActionPipeline es la única ruta de ejecución para todas las operaciones protegidas. Resuelve qué guardias se aplican, las evalúa y bloquea o ejecuta la acción.

public sealed class ActionPipeline : IActionPipeline
{
    public async Task<ActionPipelineResult> ExecuteAsync(
        string actionName,
        ActionGuardContext context,
        Func<Task> action,
        CancellationToken ct = default)
    {
        var result = await EvaluateAsync(actionName, context, ct);
        if (!result.IsAllowed) return result;

        await action();  // All guards passed — execute

        return result;   // Return modifications for caller
    }
}

El método EvaluateAsync hace el trabajo pesado:

public async Task<ActionPipelineResult> EvaluateAsync(
    string actionName,
    ActionGuardContext context,
    CancellationToken ct = default)
{
    // 1. Which plugins are enabled for this tenant?
    var enabledPlugins = await _resolver.GetEnabledPluginIdsAsync();

    // 2. Which guards match this action?
    var applicable = _guards
        .Where(g => enabledPlugins.Contains(g.PluginId))
        .Where(g => g.ActionName == null || g.ActionName == actionName)
        .ToList();

    // 3. Evaluate each guard
    var denials = new List<ActionGuardResult>();
    var modifications = new List<ActionGuardResult>();

    foreach (var guard in applicable)
    {
        try
        {
            var guardResult = await guard.EvaluateAsync(context, _services, ct);
            if (!guardResult.IsAllowed)
                denials.Add(guardResult);
            else if (guardResult.Modifications?.Count > 0)
                modifications.Add(guardResult);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Guard threw. Treating as Allow.");
        }
    }

    // 4. Any denial blocks the whole action
    if (denials.Count > 0)
        return ActionPipelineResult.Blocked(denials);

    return modifications.Count > 0
        ? ActionPipelineResult.Allowed(modifications)
        : ActionPipelineResult.Allowed();
}

Tres importantes decisiones de diseño aquí:

Resolución por inquilino. El TenantPluginResolver comprueba qué plugins tiene instalados y habilitados cada inquilino. Una guardia para un plugin deshabilitado nunca se ejecuta.
Todo-debe-pasar. Si alguna guarda deniega, la acción se bloquea. Esta es una postura de seguridad deliberada.
Guard errors fail open. Si un guard lanza una excepción, se registra y se trata como Allow(). Esto evita que un plugin roto bloquee toda la plataforma.

Resolución de plugins por inquilino

La resolución consulta la tabla TenantPluginInstallations (automáticamente delimitada al inquilino actual por los filtros de consulta globales de EF):

public sealed class TenantPluginResolver : ITenantPluginResolver
{
    public async Task<IReadOnlySet<string>> GetEnabledPluginIdsAsync(
        CancellationToken ct = default)
    {
        if (_cache is not null) return _cache;

        var ids = await _db.TenantPluginInstallations
            .Where(i => i.IsEnabled)
            .Select(i => i.PluginId)
            .ToListAsync(ct);

        _cache = ids.ToHashSet();
        return _cache;
    }
}

Efectos secundarios basados en eventos

Las acciones son síncronas. Los efectos secundarios no lo son. Una vez completada una acción, el servicio publica un evento de dominio:

await _eventPublisher.PublishAsync(
    EventNames.Entry.Created, entry.Id, new { entry.OriginalLanguage });

Los eventos se ponen en cola en un canal en memoria y son procesados por un EventConsumerWorker en segundo plano. El trabajador enruta los eventos a múltiples sistemas:

Seguimiento de la actividad. Registra quién hizo qué, cuándo
Facturación de traducciones. Rastrea los costes por proveedor
Cualquier plugin puede suscribirse a los eventos del dominio.

Los manejadores de eventos del plugin implementan IPluginEventHandler:

public interface IPluginEventHandler
{
    string PluginId { get; }
    IReadOnlyList<string> SubscribedEvents { get; }

    Task HandleAsync(
        string eventName, Guid entityId,
        Guid? tenantId, Guid? userId,
        string payloadJson, IServiceProvider services,
        CancellationToken ct = default);
}

El trabajador sólo invoca manejadores cuyo plugin está habilitado para el tenant. Esto significa que los efectos secundarios del plugin A nunca se filtran a un tenant que sólo tenga instalado el plugin B.

El motor de traducción a nivel de bloque

Aquí es donde la arquitectura da sus frutos de forma más visible.

Traducción a nivel de bloque: sólo se retraducen los bloques modificados](/es/blog/img/block-translation.svg)

Las plataformas tradicionales traducen documentos enteros. Nosotros traducimos bloques individuales: párrafos, encabezados, elementos de listas. Cuando un usuario edita un párrafo en un documento de 50 bloques, sólo es necesario volver a traducir ese párrafo. Ésa es la fuente de nuestro 94% de ahorro de costes.

Cómo se crean los bloques a partir de TipTap JSON

Cuando un usuario guarda un documento, el editor TipTap envía JSON de la siguiente forma:

{
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "attrs": { "blockId": "a1b2c3d4-..." },
      "content": [{ "type": "text", "text": "Hello world" }]
    }
  ]
}

El BlockTranslationService analiza este JSON y crea registros EntryBlock individuales:

public async Task<List<EntryBlock>> CreateBlocksFromDocumentAsync(
    Guid entryId, string language, string contentJson,
    int version, Guid userId)
{
    var doc = JsonDocument.Parse(contentJson);
    var content = doc.RootElement.GetProperty("content");

    int position = 0;
    foreach (var node in content.EnumerateArray())
    {
        var blockType = node.GetProperty("type").GetString();
        var blockJson = JsonSerializer.Serialize(node);

        // Strip metadata attrs before hashing
        var hashInput = StripBlockMetaAttrs(blockJson);

        var block = new EntryBlock
        {
            Id = ExtractOrGenerateBlockId(node),
            EntryId = entryId,
            Language = language,
            Position = position++,
            BlockType = blockType,
            ContentJson = blockJson,
            ContentHash = CalculateContentHash(hashInput),
            IsNoTranslate = ExtractNoTranslateFlag(node),
            Version = version,
        };

        _context.EntryBlocks.Add(block);
    }

    await _context.SaveChangesAsync();
    return blocks;
}

hash SHA256 para detección de caducidad

El hash del contenido es el núcleo de la detección de caducidad. Hacemos un hash del contenido del bloque (después de eliminar los atributos de metadatos como blockId y deleted) utilizando SHA256:

private string CalculateContentHash(string content)
{
    using var sha256 = SHA256.Create();
    var hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(content));
    return Convert.ToHexString(hashBytes);
}

Cuando cambia un bloque fuente, cambia su hash. El sistema compara entonces el SourceContentHash de cada bloque de traducción con el hash de origen actual, y las discrepancias se marcan como Stale:

public async Task MarkTranslationsAsStaleAsync(List<Guid> changedBlockIds)
{
    var affected = await _context.TranslationBlocks
        .Where(t => changedBlockIds.Contains(t.SourceBlockId))
        .ToListAsync();

    foreach (var translation in affected)
    {
        translation.Status = TranslationStatus.Stale;
        translation.UpdatedAt = DateTime.UtcNow;
    }

    await _context.SaveChangesAsync();
}

Adaptación de la estructura

Los traductores pueden cambiar los tipos de bloque de un idioma a otro. Una lista con viñetas en inglés puede convertirse en una lista numerada en alemán, una preferencia cultural. El sistema hace un seguimiento de esto:

var translation = new TranslationBlock
{
    SourceBlockId = sourceBlockId,
    Language = targetLanguage,
    BlockType = translatedBlockType,
    SourceBlockType = sourceBlock.BlockType,
    IsStructureAdapted = translatedBlockType != sourceBlock.BlockType,
    SourceContentHash = sourceBlock.ContentHash,
    Status = TranslationStatus.UpToDate,
};

Proveedores de traducción como plugins

Los servicios de traducción externos (DeepL, Google Translate, etc.) se conectan a través de ITranslationProviderPlugin:

public interface ITranslationProviderPlugin : IRasepiPlugin
{
    string[] GetSupportedLanguages();

    Task<string> TranslateAsync(
        string text, string sourceLanguage, string targetLanguage);

    Task<TranslationBatchResult> TranslateBatchAsync(
        Dictionary<string, string> texts,
        string sourceLanguage, string targetLanguage);
}

El método por lotes recibe un diccionario de identificadores de bloque a contenido, los traduce todos y devuelve las traducciones con un recuento de caracteres facturados. Como sólo enviamos los bloques antiguos, no todo el documento, los costes se mantienen al mínimo.

Aislamiento del inquilino: la red de seguridad invisible

Todos los sistemas descritos anteriormente funcionan dentro de un estricto aislamiento de inquilinos.

El TenantContextMiddleware resuelve el inquilino a partir del JWT en cada solicitud y verifica la pertenencia:

public async Task InvokeAsync(
    HttpContext context, TenantContext tenantContext, RasepiDbContext db)
{
    var tenantIdClaim = context.User.FindFirstValue("tenant_id");
    var userIdClaim = context.User.FindFirstValue(ClaimTypes.NameIdentifier);

    // Populate scoped context
    tenantContext.TenantId = Guid.Parse(tenantIdClaim);
    tenantContext.UserId = Guid.Parse(userIdClaim);

    // Verify membership — fail closed
    var membership = await db.TenantMemberships
        .Where(m => m.TenantId == tenantContext.TenantId
                  && m.UserId == tenantContext.UserId)
        .FirstOrDefaultAsync();

    if (membership == null)
    {
        context.Response.StatusCode = 401;
        return;  // No membership = no access
    }
}

Los filtros de consulta globales de Entity Framework garantizan que, incluso si un desarrollador se olvida de filtrar por inquilino, la capa de base de datos lo haga automáticamente:

modelBuilder.Entity<Hub>()
    .HasQueryFilter(h => h.TenantId == _tenantContext.TenantId);

El resultado: db.Hubs.ToListAsync() siempre devuelve sólo los centros del inquilino actual. Las fugas de datos requieren eludir activamente el filtro de consulta, lo que está prohibido en nuestra base de código.

La imagen completa

Cuando un usuario hace clic en "Publicar" en una entrada, esto es lo que ocurre:

La solicitud entra. La autenticación valida el JWT, TenantContextMiddleware resuelve y verifica el arrendatario.
El controlador llama a la tubería. IActionPipeline.ExecuteAsync("Entry.Publish", context, action)
Pipeline resuelve guardias. Consulta qué plugins tiene habilitados el inquilino, selecciona las guardias aplicables.
Las guardias evalúan. La guardia Workflow comprueba las aprobaciones, la guardia Retention comprueba la política, la guardia Rules valida el contenido. ¿Todos pasan? La entrada se publica.
**Se pone en cola el evento Entry.Published. Un trabajador en segundo plano registra la actividad, actualiza la facturación de la traducción y llama a los controladores de eventos del plugin.
**Se identifican los bloques obsoletos para su retraducción.

Cada capa hace su trabajo. Ninguna capa se mete en otra. Esa es la arquitectura.

No construimos esto porque la extensibilidad esté de moda. Lo construimos porque una plataforma de documentación que no pueda adaptarse al flujo de trabajo de cada equipo acabará siendo sustituida por otra que sí pueda hacerlo. Y una plataforma que se adapta sin guardarraíles acabará rompiendo algo que importa.