Rasepi Blog

Leitores e escritores estão em modos mentais diferentes. Porque é que todas as ferramentas lhes dão a mesma interface de utilizador?

2026-04-03T00:00:00Z

Abra o Confluence agora mesmo e encontre um documento que precise de ler. O que é que vê?

Uma barra de ferramentas. Botões de edição. Caixas de comentários. Ligações para o histórico da página. Uma barra lateral cheia de navegação de que não precisa. Pistas de navegação. Campos de metadados. Indicadores de permissão. Toda uma interface de criação em torno do texto que veio aqui para ler.

Agora pense no que realmente queria: a resposta a uma pergunta, ou os três passos seguintes de um processo, ou uma política que precisa de consultar antes de uma reunião daqui a dez minutos.

Veio para consumir. A interface pressupõe que veio para criar.

Este é o padrão em quase todas as plataformas de documentação. Confluence, Notion, SharePoint, GitBook, Nuclino, Slite. Todas elas apresentam o mesmo ambiente aos leitores e escritores. A página é a página. Toda a gente tem a mesma visão, com mais ou menos alguns botões com permissões.

Parece normal porque nunca tivemos outra coisa. Mas é uma decisão de design, não uma lei da natureza. E é a decisão errada.

Ler e escrever não são a mesma tarefa cognitiva

Isto não é uma preferência de interface. Trata-se de uma diferença fundamental na forma como o cérebro funciona.

Quando se escreve, está-se em modo generativo. Está a construir, a organizar, a decidir o que incluir e o que deixar de fora. Precisa de ferramentas: opções de formatação, controlos de estrutura, incorporação de suportes, campos de metadados, histórico de versões, funcionalidades de colaboração. A interface deve proporcionar-lhe poder e flexibilidade.

Quando se lê, está-se em modo recetivo. Está a analisar, a filtrar, a extrair o que é relevante e a tentar seguir em frente. Necessita de clareza: tipografia limpa, disposição clara, distração mínima. A interface deve sair do caminho.

A psicologia cognitiva tem uma estrutura clara para isto. A [Teoria da Carga Cognitiva] (https://www.instructionaldesign.org/theories/cognitive-load/), desenvolvida por John Sweller no final dos anos 80, distingue entre carga intrínseca (a dificuldade do material em si), carga germânica (o esforço de aprendizagem e integração) e carga externa (tudo o que o ambiente acrescenta que não ajuda). Todas as barras de ferramentas, barras laterais e botões de edição visíveis para um leitor são cargas estranhas. Não os ajuda a compreender o conteúdo. Concorre ativamente pela atenção.

A investigação de [Mayer e Moreno (2003)] (https://doi.org/10.1207/S15326985EP3801_6) sobre a aprendizagem multimédia demonstrou que a redução de elementos estranhos melhora a compreensão e a retenção. O seu princípio de coerência é direto: Uma interface de documentação que mostra os controlos de criação aos leitores está a violar este princípio em cada carregamento de página.

**O leitor não precisa de ver as ferramentas do autor. Mostrá-las na mesma não é neutro. É ativamente prejudicial para a compreensão.

Como é que as plataformas actuais lidam com isto (a maioria não lida)

Vejamos o que existe.

O Confluence tem um modo de leitura e um modo de edição, mas o modo de leitura ainda está rodeado pela navegação, metadados e árvore de páginas da plataforma. A barra de ferramentas de edição desaparece quando não se está a editar, mas o quadro mental de "esta é uma página wiki editável" nunca desaparece completamente. Todos os leitores vêem o botão "Editar". A página sussurra: podes mudar isto.

O Notion é pior neste aspeto. A sua principal filosofia de design é que tudo é sempre editável. Clique em qualquer lugar e está a escrever. Isso é ótimo para os escritores. É terrível para os leitores que querem apenas absorver o conteúdo sem a ansiedade de modificar algo acidentalmente. A própria [galeria de modelos] do Notion (https://www.notion.com/templates) mostra isso: cada modelo é um espaço de trabalho, não uma publicação.

O SharePoint suporta tecnicamente diferentes layouts de página para visualização e edição, mas a experiência geral continua a ser uma intranet corporativa. Os leitores sentem-se como se estivessem dentro de uma ferramenta empresarial e não a ler um documento optimizado para a compreensão.

O GitBook é o que mais se aproxima de uma experiência de leitura em primeiro lugar, com a sua saída limpa ao estilo de documentação. Mas mesmo aí, a experiência de leitura serve o pressuposto de que o leitor é um programador que está a olhar para documentos técnicos. Não foi concebido para o consumidor de conhecimentos gerais.

Nenhuma destas plataformas trata a leitura como uma atividade fundamentalmente diferente da escrita. Tratam-na como escrever com a barra de ferramentas escondida.

Ferramentas actuais: uma interface, todos os públicos](/pt/blog/img/leitores-escritores-ferramentas-actuais.svg)

O custo de uma interface única

Este não é apenas um problema estético. Tem consequências mensuráveis.

A sobrecarga de informação reduz a compreensão

Um [estudo publicado no Journal of Consumer Research] (https://doi.org/10.1086/209336) descobriu que a sobrecarga de informação leva a uma pior qualidade de decisão, com o efeito a aumentar à medida que o rácio entre informação irrelevante e relevante cresce. Uma página de documentação com controlos de criação visíveis, árvores de navegação e campos de metadados aumenta esse rácio para todos os leitores que não estão lá para escrever.

A mudança de contexto tem um custo real

Quando um sinal de interface diz "pode editar isto", ativa um quadro cognitivo diferente de "leia isto". A investigação de Gloria Mark na UC Irvine sobre atenção e multitarefas concluiu que são necessários, em média, 23 minutos e 15 segundos para voltar a concentrar-se totalmente após uma mudança de contexto. Um leitor que considere momentaneamente a hipótese de editar (mesmo para corrigir uma gralha) foi retirado do modo de leitura. Não se trata de uma hipótese. Qualquer pessoa que tenha utilizado o Notion conhece a experiência de clicar para selecionar texto e acidentalmente começar a escrever.

Leitores e escritores têm necessidades diferentes para o mesmo conteúdo

Um escritor precisa de ver a estrutura, os marcadores de formatação, os tipos de blocos, os metadados e os sinais de colaboração. Precisa de toda a maquinaria.

Um leitor precisa de ver texto limpo, hierarquia clara e o caminho mais rápido para a informação que procura. Precisa do conteúdo, não da maquinaria.

Servir ambos a partir da mesma interface significa que nenhum deles obtém uma experiência optimizada para o que estão realmente a fazer.

E depois há o terceiro público: A IA

É aqui que tudo se complica e que as plataformas existentes não estão preparadas.

A documentação em 2026 tem três consumidores distintos, não dois:

Escritores que criam e mantêm conteúdos
Leitores que consomem conteúdos visualmente
Sistemas de IA que recuperam, analisam e sintetizam conteúdos de forma programática

Cada um destes públicos necessita de uma interface fundamentalmente diferente para o mesmo conteúdo subjacente.

Os escritores precisam de ferramentas de edição ricas, funcionalidades de colaboração e controlos estruturais. Os leitores precisam de uma apresentação clara e concentrada, com o mínimo de distracções. A IA necessita de resultados estruturados e analisáveis por máquina com metadados explícitos: sinais de atualidade, etiquetas de classificação, endereçamento ao nível do bloco e marcação semântica clara.

Como discutimos em Builders, Not Developers, os intermediários de IA já são o consumidor dominante de documentação para uma parte crescente dos trabalhadores do conhecimento. A pesquisa de desenvolvedores do GitHub de 2024 descobriu que 97% dos desenvolvedores corporativos usaram ferramentas de codificação de IA. Em 2026, [84% dos programadores utilizam regularmente ferramentas de IA] (https://www.index.dev/blog/developer-productivity-statistics-with-ai-tools), sendo que 41% de todo o código é gerado por IA.

Estes sistemas de IA não querem saber da sua barra lateral ou da sua barra de ferramentas. Eles precisam de dados limpos. E uma plataforma que confunde a visão do leitor com a visão do escritor também está a confundir a superfície consumível pela IA com a superfície de criação humana. São três incompatibilidades numa só interface.

Três públicos, três necessidades diferentes] (/blog/img/leitores-escritores-três-audiências.svg)

Como o Rasepi separa as experiências

O Rasepi foi concebido com base no princípio de que criar conteúdos e consumir conteúdos são actividades diferentes que merecem interfaces diferentes.

O ambiente do escritor

Quando está a escrever no Rasepi, obtém um ambiente de criação completo. Edição de texto rico com TipTap, controlos ao nível do bloco, indicadores de estado da tradução, gestão de expiração, ferramentas de colaboração, vistas da estrutura de conteúdos e tudo o que um escritor precisa para criar e manter documentação de alta qualidade.

O escritor vê a maquinaria porque precisa da maquinaria.

O ambiente do leitor

Quando alguém consome um documento Rasepi, vê uma experiência de leitura limpa e focada. Sem chrome de edição. Sem barras de ferramentas. Sem sinais de "pode modificar isto". Apenas o conteúdo, apresentado num esquema optimizado para compreensão e leitura.

O leitor não vê o botão de edição porque não está aqui para editar. Está aqui para aprender algo, seguir um processo ou encontrar uma resposta. A interface respeita essa intenção.

A superfície da IA

Para os consumidores de IA, o Rasepi expõe o conteúdo através de APIs estruturadas com metadados completos. Cada bloco tem a sua pontuação de frescura, estado de tradução, hash de conteúdo e etiquetas de classificação. Os sistemas de IA podem consultar o conteúdo ao nível do bloco, filtrar por frescura, excluir material obsoleto ou de rascunho e obter exatamente os dados estruturados de que necessitam.

Não é preciso raspar uma página wiki e esperar pelo melhor. A IA obtém uma interface criada para o efeito, tal como o leitor e o escritor.

Uma camada de conteúdo, três interfaces

O importante é que não estamos a manter três cópias do conteúdo. Este não é o problema das cinco cópias de integração que discutimos em [Stop Maintaining Five Copies of the Same Document] (/blog/stop-maintaining-five-copies-of-the-same-document/).

Trata-se de uma camada de conteúdo, armazenada como blocos estruturados, servida através de três vistas diferentes optimizadas para três públicos diferentes.

O redator edita os blocos. O leitor vê o conteúdo montado e estilizado. A IA consulta dados estruturados com metadados. Os mesmos blocos. A mesma fonte de verdade. Camada de apresentação diferente para cada consumidor.

Isto só é possível devido à arquitetura ao nível dos blocos. Cada conteúdo é uma unidade individualizável com os seus próprios metadados. Pode apresentar esses blocos de forma diferente, dependendo de quem os está a pedir:

Audiência	Necessidades	Obtém
Ambiente de criação completo com controlos ao nível dos blocos
Leitor**	Texto limpo, hierarquia clara, digitalização rápida	Vista de leitura focada, sem cromo de edição
API a nível de bloco com metadados completos

Porque é que isto é mais importante do que parece

Poderá ler isto e pensar: "É apenas a interface do utilizador. Vistas diferentes da mesma coisa. Quão importante pode ser?"

Muito importante, ao que parece.

Confiança do leitor

As pessoas confiam em conteúdos que parecem publicados. Quando uma página parece um wiki que qualquer pessoa pode editar, os leitores inconscientemente desconfiam dela. Quando o mesmo conteúdo é apresentado numa visualização de leitura limpa e com qualidade de publicação, tem mais autoridade. Isto não é irracional. É um sinal de que alguém levou a apresentação a sério, o que implica que também levou o conteúdo a sério.

O Nielsen Norman Group estudou extensivamente esta questão. A sua [investigação sobre a credibilidade do conteúdo] (https://www.nngroup.com/articles/trust-signals-content/) mostra que a qualidade do design e a apresentação são dos sinais mais fortes em que os utilizadores confiam para avaliar a fiabilidade do conteúdo. Uma vista de editor desordenada prejudica ativamente a credibilidade do conteúdo que apresenta.

Produtividade do escritor

Os escritores que trabalham num ambiente de criação dedicado não têm de alternar entre "estou a ler ou estou a escrever?". As ferramentas estão lá porque é suposto estarem lá, não porque a interface não consegue decidir quem está a olhar para ela.

Fiabilidade da IA

Quando os sistemas de IA têm uma superfície criada para o efeito com metadados estruturados, podem tomar melhores decisões sobre o que recuperar e o que excluir. Podem verificar as pontuações de atualidade antes de incluir um bloco numa resposta. Podem respeitar as etiquetas de classificação. Podem filtrar por idioma, estado ou público. Nada disto é possível quando a IA está a extrair a mesma página HTML que foi concebida para leitores humanos.

A mudança de modelo mental

O pressuposto fundamental da maioria das plataformas de documentação é: a página é a unidade, e toda a gente interage com a página.

O pressuposto do Rasepi é diferente: O pressuposto do Rasepi é diferente: o bloco é a unidade, e diferentes públicos interagem com os blocos através de superfícies criadas para o efeito.

Isto parece uma pequena distinção arquitetónica. Mas não é. É a diferença entre uma ferramenta que mostra acidentalmente conteúdos a sistemas de IA e uma que os serve deliberadamente. Entre um ambiente de escrita que por acaso é legível e uma experiência de leitura que foi concebida de raiz. Entre uma interface suficientemente boa e três excelentes.

A documentação já não é apenas escrita e lida. É escrita, lida, consultada, traduzida, pontuada, classificada e fornecida a sistemas de IA em grande escala. Uma única interface não pode otimizar tudo isso, e fingir que pode é a razão pela qual acabámos com wikis que ninguém quer ler e assistentes de IA a extrair respostas de páginas que nunca foram concebidas para serem consumidas por máquinas.

Os leitores e os escritores estão em modos mentais diferentes. A IA está num modo completamente diferente. A interface deve refletir isso mesmo.

O estado dos documentos em 2026: cinco tendências que definirão a próxima era

2026-04-03T00:00:00Z

De tempos a tempos, reservo uma manhã para ler. Não o código Rasepi, não os problemas do GitHub. Blogs de concorrentes, relatórios do setor, anúncios de palestras, pesquisas com desenvolvedores. O que quer que tenha sido lançado no último trimestre e que tenha a ver com documentação, gestão do conhecimento ou fluxos de trabalho assistidos por IA.

Fiz isso na semana passada, e a imagem que surgiu foi mais nítida do que eu esperava. Não porque um único anúncio tenha sido inovador, mas porque cinco tendências distintas estão a convergir e, quando as alinhamos, elas traçam um quadro muito claro do que as plataformas de documentação terão de fazer nos próximos dois anos.

Eis o que descobri.

1. A IA é o principal leitor agora. Não os humanos.

O GitBook publicou um número impressionante em seu [relatório de dados de documentos de IA] (https://www.gitbook.com/blog/ai-docs-data-2025): A leitura de documentação por IA aumentou mais de 500% em 2025. Quinhentos por cento. Isso não é um erro de arredondamento.

Enquanto isso, o [2024 Developer Survey] do Stack Overflow (https://survey.stackoverflow.co/2024/) mostrou que 61% dos desenvolvedores gastam mais de 30 minutos por dia procurando respostas. Mas a forma como eles pesquisam mudou. A própria pesquisa do GitHub descobriu que 97% dos desenvolvedores corporativos usaram ferramentas de codificação de IA. Até 2026, 84% dos desenvolvedores usam ferramentas de IA diariamente, com 41% do código agora gerado por IA. Estas pessoas não estão a navegar na barra lateral do seu wiki. Estão a perguntar ao Claude ou ao Copilot, e a IA está a ler os seus documentos em nome delas.

A implicação é difícil de exagerar. O seu consumidor mais frequente de documentação já não é uma pessoa com um separador do browser aberto. É um modelo de linguagem que faz chamadas de recuperação. E esse modelo não tem capacidade para olhar para uma página e pensar "hmm, isto parece desatualizado".

O GitBook apercebeu-se disso cedo e respondeu com o seu relatório State of Docs 2026 e um impulso para formatos legíveis por máquinas. Também lançaram o skill.md, uma convenção para estruturar informações sobre produtos especificamente para agentes de IA. A Google foi mais longe com o seu Gemini API Docs MCP, que liga os agentes de codificação à documentação atual através do Protocolo de Contexto de Modelo. O seu raciocínio foi explícito: os agentes geram código desatualizado porque os seus dados de treino têm uma data limite. A correção do MCP elevou a taxa de aprovação da avaliação para 96,3%.

Portanto, a primeira tendência está estabelecida. A IA é o leitor principal. As plataformas que tratarem este facto como uma restrição de conceção fundamental, e não como uma funcionalidade a acrescentar mais tarde, terão uma vantagem estrutural.

2. A frescura e os metadados de confiança estão a tornar-se obrigatórios

A Anthropic entrevistou 81.000 utilizadores do Claude em dezembro de 2025 e publicou os resultados em março de 2026. É o maior estudo qualitativo de utilizadores de IA alguma vez realizado (159 países, 70 línguas). A preocupação mais citada? A falta de fiabilidade. 27% dos inquiridos indicaram-na como a sua principal preocupação, e 79% dessas pessoas tinham-na experimentado em primeira mão.

Este número deveria deixar qualquer equipa de documentação acordada à noite.

Quando as respostas da IA não são fiáveis, o problema nem sempre é o modelo. Muitas vezes, o modelo está a reproduzir fielmente o que encontrou num documento obsoleto. O modelo não alucinou. Os seus documentos estavam simplesmente errados e ninguém os assinalou.

Os dados do Stack Overflow reforçam isso de um ângulo diferente: 81% dos programadores esperam que a IA seja mais integrada na forma como documentam o código no próximo ano. Se 81% dos seus utilizadores estão a fornecer documentos à IA, e 27% dos utilizadores de IA dizem que a falta de fiabilidade é o maior problema, tem um problema de confiança que nenhuma quantidade de engenharia rápida resolve. A correção está na fonte.

É por isso que os metadados de atualidade são importantes. Não os carimbos de data/hora da "última edição" (estes dizem-nos quando alguém tocou no ficheiro, não se o conteúdo ainda está correto). Frescura real: estado da revisão, saúde da ligação, alinhamento da tradução, sinais de leitura, deteção de desvios de conteúdo. Metadados que uma máquina pode ler e utilizar para decidir se um documento é seguro para citar.

Estou sempre a voltar a um enquadramento simples. A sua documentação precisa de uma pontuação de crédito. Não um registo de data e hora. Uma pontuação de crédito. (Temos estado a construir exatamente isto com o [sistema de pontuação de frescura] do Rasepi(/features/freshness) e, honestamente, ver os dados da indústria só me deixa mais convencido de que é a decisão certa).

3. A tradução está a passar de "projeto" para "pipeline"

DeepL publicou um artigo em fevereiro intitulado ["The 6 Translation Transformations Global Businesses Can't Afford to Miss"] (https://www.deepl.com/en/blog/six-translation-transformations). O seu argumento: a tradução está a tornar-se um desafio operacional contínuo e não um projeto de lote que se realiza trimestralmente.

Isto está de acordo com tudo o que vejo.

O modelo antigo era simples. Escrever em inglês. Quando se tem orçamento, contrata-se um tradutor ou recorre-se a um serviço. Receber as traduções. Carregue-as. Está feito até à próxima vez. O problema é que a "próxima vez" chega cada vez mais depressa quando o seu produto é enviado semanalmente e os seus documentos são actualizados constantemente. Na altura em que a versão alemã volta da revisão, a versão inglesa já foi alterada duas vezes.

O [Customization Hub] (https://www.deepl.com/customization-hub) do próprio DeepL agora oferece glossários, regras de estilo e configurações de formalidade, o que é ótimo. Mas se essas ferramentas estiverem fora da sua plataforma de documentação, está a gerir uma cadeia de ferramentas de tradução: editor, exportar, traduzir, rever, reimportar, repetir. Cada passo é uma oportunidade para se desviar.

O Notion não tem suporte multilingue nativo. O Confluence oferece-o através de plugins do mercado. O GitBook adicionou a tradução automática em agosto de 2025, que é um passo, mas funciona ao nível da página.

A verdadeira mudança é do nível da página para o nível do bloco. Quando se controlam as traduções ao nível do parágrafo, só se retraduz o que realmente mudou. Uma edição típica afecta talvez dois parágrafos em quarenta. Isso representa 94% menos trabalho de tradução. (Esta é a arquitetura de tradução principal do Rasepi e, honestamente, a coisa de que mais me orgulho no produto. Mas mesmo deixando-nos de lado, a direção da indústria é clara: tradução contínua, incremental e incorporada é para onde isto se dirige).

4. Os agentes de IA precisam de conteúdo estruturado, não de páginas wiki

Esta questão cristalizou-se para mim quando a Notion anunciou [Custom Agents] (https://www.notion.com/blog/introducing-custom-agents) em fevereiro. 21.000 agentes construídos durante o acesso antecipado. Agentes que respondem a perguntas de bases de conhecimento, encaminham tarefas, compilam relatórios de estado. Só o Ramp tem mais de 300 agentes.

A Atlassian seguiu uma direção semelhante. A Rovo AI in Confluence extrai contexto de toda a Atlassian e de aplicações de terceiros para gerar conteúdo. A sua proposta: "conteúdo rico em contexto e de alta qualidade baseado no trabalho existente da sua equipa".

E depois a Anthropic lançou equipas de agentes no Claude Code, onde vários agentes de IA se coordenam autonomamente em tarefas complexas. O Opus 4.6 tem uma pontuação de 76% no benchmark MRCR de 1M com 8 agulhas (acima dos 18,5% do modelo anterior), o que significa que pode realmente recuperar informações enterradas em grandes conjuntos de documentos sem perder o rasto.

As três empresas estão a criar agentes que consomem documentação. Nenhuma delas resolveu o problema da qualidade da fonte.

A documentação dos agentes personalizados da Notion reconhece explicitamente o [risco de injeção imediata] (https://www.notion.com/blog/introducing-custom-agents) quando os agentes lêem conteúdo não confiável. O Rovo da Atlassian pega tudo o que encontra no seu Confluence. Se esse conteúdo estiver três meses desatualizado, o Rovo não sabe. Ele se baseia nele de qualquer maneira.

Para que os agentes trabalhem de forma confiável, eles precisam de mais do que páginas de texto. Precisam de conteúdo estruturado com identificadores estáveis, sinais de atualização explícitos, metadados de classificação claros e a capacidade de distinguir "isto é atual e revisto" de "isto existe mas ninguém lhe toca há um ano". As páginas Wiki não oferecem isso. O conteúdo estruturado ao nível do bloco com metadados de confiança fornece-o.

5. O código aberto e a auto-hospedagem estão a regressar

Este último é mais um pressentimento apoiado por dados do que um anúncio único.

GitBook open-sourced sua documentação publicada no final de 2024 e lançou um fundo OSS. O seu raciocínio: os projectos de código aberto merecem ferramentas de documentação gratuitas e de alta qualidade. Mas o movimento também sinaliza algo mais amplo.

O Notion é apenas na nuvem. Não há opção de auto-hospedagem. O Confluence Data Center existe, mas requer uma licença. Quando a sua plataforma de documentação contém o seu conhecimento operacional mais sensível (manuais de incidentes, procedimentos de conformidade, decisões de arquitetura), a questão de "quem controla estes dados?" não é abstrata.

O post do Anthropic "Claude is a space to think" de fevereiro apresentou um argumento interessante sobre confiança e modelos de negócio. A sua alegação principal: os incentivos publicitários são incompatíveis com um assistente de IA genuinamente útil. Optaram por não ter publicidade para que os utilizadores possam confiar na ferramenta.

Penso que existe um paralelo para as plataformas de documentação. Se o seu sistema de documentação é de código fechado e apenas na nuvem, não pode verificar o que alimenta a IA. Não é possível auditar os cálculos de atualização. Não pode garantir que os seus dados permaneçam sob o seu controlo. Para as equipas que estão a implementar assistentes de IA sobre a sua base de conhecimentos (e cada vez mais, todos o fazem), a auditabilidade é importante.

Esta não é uma polémica sobre o código aberto ser moralmente superior. Os produtos de código fechado podem ser absolutamente fiáveis. Mas quando se está a construir fluxos de trabalho com IA em cima da documentação interna, a capacidade de inspecionar e verificar o sistema é uma vantagem prática. Para nós, o licenciamento do Rasepi pelo MIT não foi uma reflexão tardia. Foi uma decisão de design baseada na mesma lógica: a infraestrutura de documentação deve ser auditável.

O que estas cinco tendências significam em conjunto

Individualmente, cada uma dessas tendências é gerenciável. A IA lê os seus documentos? Muito bem, adicione alguns metadados legíveis por máquina. A atualidade é importante? Ótimo, adicione datas de revisão. A tradução precisa de ser contínua? Claro, integre DeepL. Os agentes precisam de estrutura? É justo, melhore o seu modelo de conteúdos. A soberania é importante? Ótimo, ofereça uma opção auto-hospedada.

Mas, em conjunto, descrevem uma plataforma que é fundamentalmente diferente da que a maioria das equipas utiliza atualmente.

A diferença é arquitetónica. Não se trata de cinco funcionalidades que se acrescentam. São cinco pressupostos que precisam de ser incorporados na base. Como o conteúdo é armazenado (a nível de bloco, não a nível de página). Como a confiança é modelada (pontuações de frescura, não carimbos de data/hora). Como funciona a tradução (incremental, incorporada, por parágrafo). Como é que os agentes de IA acedem ao conteúdo (APIs estruturadas com metadados, e não scrapes de páginas). Como é que os dados são controlados (abertos, auditáveis, auto-hospedados).

Nenhuma plataforma estabelecida foi concebida em torno de todos estes cinco aspectos em simultâneo. Algumas estão a adicioná-los peça a peça. O GitBook está a avançar mais rapidamente na frente da legibilidade da IA. A Notion está a construir uma infraestrutura de agentes. A Atlassian tem uma distribuição empresarial.

Mas projetar para todos os cinco desde o primeiro dia? Essa é a vantagem de começar do zero quando o terreno muda.

Sei que estou a ser parcial. Construímos o Rasepi especificamente porque vimos estas tendências a convergir e queríamos uma plataforma que assumisse todas elas desde o início. Tradução ao nível do bloco, expiração forçada, pontuação de frescura, conteúdo estruturado pronto para IA, código aberto. É a tese de todo o projeto.

Mas mesmo que não existíssemos, penso que qualquer leitura honesta do que aconteceu no primeiro trimestre de 2026 aponta na mesma direção. A documentação está a tornar-se infraestrutura. E as infra-estruturas têm requisitos diferentes das páginas wiki.

As equipas que descobrirem isto primeiro não terão apenas melhores documentos. Terão agentes de IA mais fiáveis, custos de tradução mais baixos, menos surpresas de conformidade e bases de conhecimento que se mantêm fiáveis ao longo do tempo.

Esse é o estado dos documentos em 2026. A questão não é se essas tendências são reais. É saber se a sua plataforma foi concebida para elas.

Cinco tendências. Uma questão de arquitetura: a sua plataforma de documentação foi concebida para 2026 ou continua a servir pressupostos de 2016?

Fontes: 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 is a space to think", Claude Opus 4.6, Notion Custom Agents, Atlassian Rovo in Confluence, DeepL "6 Translation Transformations", DeepL Customization Hub, GitBook open source documentation, GitBook auto-translate.

Construtores, não desenvolvedores: Como a Claude mudou para quem são os seus documentos

2026-04-02T00:00:00Z

Há uma pessoa neste momento, algures, a integrar a sua API. Ela não está no seu site de documentação. Não abriu o seu guia de iniciação. Nunca viu o seu playground interativo ou a navegação cuidadosamente concebida na barra lateral.

Eles estão sentados no Claude. Ou no Copilot. Ou Cursor. Escreveram algo como "integrar a API de faturação Stripe com a minha aplicação Next.js utilizando o router de aplicações" e esperaram que o código de trabalho voltasse. A IA lia os seus documentos em nome deles. Encontrou os endpoints relevantes, compreendeu o fluxo de autenticação, escolheu os métodos SDK corretos e produziu uma implementação.

Há duas semanas, na Start Summit Hackathon em St. Gallen, vi isto acontecer em tempo real. Estava a falar com um grupo de estudantes de Ciências da Computação e com alguns fundadores de startups em fase inicial sobre a forma como abordam as novas API, e todos eles descreveram o mesmo fluxo de trabalho: colar o problema numa IA, receber o código de volta, iterar a partir daí. Uma das alunas riu-se quando lhe perguntei se tinha lido os documentos. "Porque é que eu havia de ler? O Claude lê-os por mim".

A pessoa nunca visitou o seu sítio. Pode ser que nunca visite o seu site. E é cada vez mais assim que o software é construído.

A principal mudança

A documentação tem agora dois consumidores fundamentalmente diferentes: os humanos que a lêem e os assistentes de IA que a lêem em nome dos construtores. A maior parte da documentação é optimizada exclusivamente para humanos. A IA já é o leitor dominante.

Isto muda tudo a jusante:

Quando uma IA serve conteúdos obsoletos, o construtor não tem forma de detetar o problema. Os danos são silenciosos.
Os gestores de produto, designers e analistas estão a enviar software através de assistentes de IA, muitas vezes sem nunca terem lido uma linha de documentação.
A estrutura legível pela máquina é mais importante do que o design visual. O markdown limpo, os blocos autónomos e os metadados explícitos são o que permite à IA representar o seu produto com precisão.
Os requisitos de formato dividiram-se.** Os leitores humanos precisam de narrativa. Os intermediários de IA precisam de especificações estruturadas e analisáveis. É necessário servir ambos.

O resto deste post revela como chegamos aqui, o que isso significa para o DevRel e o que você pode fazer sobre isso agora.

A viagem que ninguém planeou

Durante muito tempo, as relações com os programadores seguiram um caminho bem compreendido. Você escreveu uma documentação abrangente. Publicou guias de início rápido. Dava palestras em conferências. Mantinha uma presença no Stack Overflow. Tornou a referência da sua API pesquisável, os seus SDKs idiomáticos, as suas mensagens de erro úteis.

Esse caminho pressupõe que o desenvolvedor lerá seu conteúdo. Navegar na sua estrutura. Seguir os seus passos.

A pesquisa de desenvolvedores do GitHub de 2024 descobriu que 97% dos desenvolvedores corporativos já usaram ferramentas de codificação de IA em algum momento. [A pesquisa anual do Stack Overflow] (https://survey.stackoverflow.co/2024/) mostrou que 76% de todos os desenvolvedores estão usando ou planejando usar ferramentas de IA, com 62% dos profissionais usando-as ativamente no dia a dia. Em 2026, esse número subiu para 84%, com 41% de todo o código agora gerado por IA e 51% dos desenvolvedores profissionais usando ferramentas de IA diariamente. Estes números não estão a abrandar.

A nova viagem tem um aspeto diferente. Alguém descreve o que pretende em linguagem natural. Um assistente de IA lê a documentação, encontra as secções relevantes e gera a integração. O construtor revê o resultado, talvez refine o pedido, talvez faça um seguimento. Minutos, não horas.

O funil de arranque que as equipas DevRel passaram anos a aperfeiçoar? Está a ser contornado. Não por ser mau. O ponto de entrada simplesmente mudou.

Dois consumidores, um conjunto de documentos

A documentação tem agora dois públicos fundamentalmente diferentes.

O primeiro é o leitor humano. Esta pessoa ainda existe. Aparece para tomar decisões de arquitetura, depurar casos extremos, analisar a conformidade e compreender conceitos. Quer explicações narrativas, material de referência bem organizado e um raciocínio claro sobre as soluções de compromisso.

O segundo é o intermediário de IA. Este lê a sua documentação em nome de um construtor. Não se preocupa com a sua barra lateral. Não aprecia o seu design visual. Precisa de conteúdo estruturado e analisável por máquina: markdown limpo, formatação consistente, especificações explícitas sobre as quais possa raciocinar sem ambiguidade.

Atualmente, quase todos os sítios de documentação são optimizados exclusivamente para o primeiro público. O segundo público já é o consumidor dominante.

Jeremy Howard identificou esta tensão quando [propôs a norma /llms.txt] (https://llmstxt.org/) em 2024. A sua observação foi precisa: "Os grandes modelos linguísticos dependem cada vez mais de informações de sítios Web, mas enfrentam uma limitação crítica: as janelas de contexto são demasiado pequenas para lidar com a maioria dos sítios Web na sua totalidade." A proposta é simples. Um ficheiro markdown com curadoria em /llms.txt que dá aos modelos de IA uma visão geral estruturada do seu produto e ligações para os recursos mais importantes. FastHTML, os próprios documentos do Anthropic e um [diretório crescente de projectos] (https://llmstxt.site/) já têm um.

É uma convenção útil. Mas é também um sintoma de um problema mais profundo. O verdadeiro problema não é o formato. É o facto de a maior parte da documentação nunca ter sido concebida tendo em mente o consumo por parte das máquinas.

O construtor não está a cortar nos cantos

Existe a tentação de olhar para a pessoa que pede Claude em vez de ler a documentação e concluir que ela está a tomar atalhos. Que ela não entende realmente o que está acontecendo no código. Que ela é, de alguma forma, um desenvolvedor inferior.

Já tive esta conversa vezes suficientes para saber que isso é normalmente errado.

Muitos destes construtores são engenheiros sénior que fazem escolhas deliberadas de eficiência. Eles entendem o código, só não querem navegar por quatro páginas de documentação para encontrar as três linhas de que realmente precisam. Eles aprenderam que um assistente de IA pode extrair essas linhas mais rápido do que eles podem procurar por elas, então eles delegam a leitura. (Honestamente, eu próprio faço isto. Não me lembro da última vez que li um guia de iniciação de cima a baixo).

A Anthropic reconheceu este padrão quando construiu o [Model Context Protocol] (https://modelcontextprotocol.io/introduction). O MCP é agora suportado pelo Claude, ChatGPT, VS Code, Cursor, entre outros. Foi explicitamente concebido para que os assistentes de IA possam aceder a sistemas externos, obter contexto e agir com base nele. A especificação descreve-a como fornecendo "acesso a um ecossistema de fontes de dados, ferramentas e aplicações que irão aumentar as capacidades e melhorar a experiência do utilizador final".

Leia isto com atenção. É uma linguagem de infraestrutura, não de conveniência. Os construtores que utilizam estas ferramentas não estão a evitar o trabalho. Estão a trabalhar através de uma nova camada, e a sua documentação faz parte dessa camada, quer a tenha concebido ou não.

Os números confirmam isso. Só o Claude lida agora com [25 mil milhões de chamadas de API por mês] (https://www.incremys.com/en/resources/blog/claude-statistics), com 30 milhões de utilizadores activos mensais em 159 países. 70% das empresas da Fortune 100 usam o Claude. De acordo com um inquérito da Menlo Ventures, a Anthropic detém 32% da quota de mercado da IA empresarial por utilização de modelos, à frente da OpenAI com 25%. Um relatório de investigação do HSBC coloca esse valor ainda mais alto: 40% do total de despesas com IA. Não se trata de ferramentas experimentais. São infra-estruturas primárias.

As relações com os programadores foram criadas para uma era diferente

Se a sua estratégia DevRel foi concebida antes de 2023, foi concebida para um mundo onde os programadores liam os documentos diretamente. Esse mundo não desapareceu, mas já não é o padrão de interação dominante para uma parte crescente dos criadores.

Isto altera o cálculo de várias actividades DevRel de longa data.

**Uma apresentação de 45 minutos numa conferência de programadores chega a uma sala com algumas centenas de pessoas. Um ficheiro /llms.txt bem estruturado e uma documentação limpa e legível por máquina chegam a todos os construtores que perguntam a qualquer assistente de IA sobre o seu produto, continuamente, em qualquer altura. A palestra é um evento único. A documentação legível por máquina é composta. Não estou a dizer que as conferências não têm valor (acabei de regressar de uma, literalmente), mas a equação de alavancagem mudou.

**O clássico tutorial de início rápido em cinco passos é cada vez mais uma formalidade. O construtor não segue passos. Descrevem o que pretendem e esperam que a IA produza a integração. Se a API estiver bem documentada num formato de fácil utilização, a IA trata da experiência de arranque de forma mais eficiente do que qualquer tutorial poderia fazer. Em vez disso, os tutoriais devem tornar-se material concetual: explicar por que razão se deve escolher a abordagem A em vez da abordagem B. A IA pode gerar a implementação. É muito menos fiável a explicar as soluções de compromisso.

**Os dados do seu próprio inquérito mostraram que 84% dos programadores utilizam a documentação técnica diretamente, sendo que 90% destes confiam na documentação contida nos pacotes API e SDK. Mas a forma como acedem a esses documentos é cada vez mais através de uma camada de IA e não de um separador do browser. As perguntas que ainda chegam ao Stack Overflow tendem a ser as mais difíceis. Casos extremos, depuração de produção, coisas que exigem nuances. Valiosas, com certeza. Mas já não é onde está o volume.

Quando a IA lê os seus documentos, a atualidade torna-se crítica

Aqui está a parte em que a maioria das equipas não pensou.

Quando um ser humano lê uma página de documentação, ele pode fazer um julgamento. Pode reparar que as capturas de ecrã parecem antigas, ou que um comentário no final diz que o processo mudou. Podem olhar para ela e pensar "isto parece desatualizado".

Um assistente de IA não pode fazer nada disso. Lê o texto, processa-o como um facto e gera uma resposta com total confiança. Se a documentação descrever um ponto final obsoleto, a IA recomendará alegremente a integração com ele. Se a documentação fizer referência a uma infraestrutura que foi substituída há seis meses, a IA descreverá a configuração antiga como atual. Sem hesitação.

E aqui está o que torna isto pior do que parece: 66% dos programadores já afirmam que o maior problema das ferramentas de IA é o facto de darem resultados que estão "quase certos, mas não totalmente". A documentação obsoleta contribui diretamente para esse problema. A IA não está a alucinar. Está a reproduzir fielmente conteúdo desatualizado, e não há forma de o construtor perceber a diferença.

O construtor confia na IA. A IA confia na documentação. Se a documentação estiver desactualizada, essa cadeia de confiança dá uma resposta seguramente errada.

Isto sempre foi um problema, obviamente. Os conteúdos obsoletos sempre confundiram as pessoas. Mas os danos foram contidos porque os leitores humanos podiam, por vezes, detectá-los. Os intermediários de IA não conseguem. Amplificam os conteúdos obsoletos, fornecendo-os em grande escala, com autoridade, a pessoas que não têm motivos para duvidar deles.

A atualidade já não é uma questão de qualidade do conteúdo. É um problema de fiabilidade para todos os fluxos de trabalho alimentados por IA que tocam nos seus documentos.

A palavra "programador" é demasiado restrita

As pessoas que estão a criar software em 2026 não se identificam todas como programadores. Alguns são designers que pedem ao Claude para construir um protótipo funcional. Alguns são gestores de produto que utilizam o Cursor para enviar ferramentas internas. Outros são analistas de dados que descrevem um pipeline de dados em linguagem natural e deixam um agente montá-lo. Na Start Summit, metade das equipas da hackathon tinha membros sem qualquer experiência em programação que, no final do fim de semana, já estavam a enviar software funcional.

A Ramp é um exemplo útil. A empresa fintech passou de uma avaliação de US $ 5.8 bilhões em 2023 para [US $ 32 bilhões no final de 2025] (https://techcrunch.com/2025/11/17/ramp-hits-32b-valuation-just-three-months-after-hitting-22-5b/), ultrapassando US $ 1 bilhão em receita anualizada ao longo do caminho. Uma das startups de crescimento mais rápido da história. Uma parte amplamente discutida de sua abordagem: gerentes de produto construindo recursos diretamente com ferramentas de IA em vez de esperar em um backlog de engenharia. Os PMs da Ramp não se limitam a escrever especificações. Eles enviam o código. A IA trata da implementação. O PM lida com a intenção.

Não é um atalho. Trata-se de um novo modelo operacional, que está a funcionar a uma escala que torna muito difícil descartá-lo como uma experiência.

O próprio estudo interno da Anthropic é revelador. Quando eles [entrevistaram 132 de seus próprios engenheiros] (https://fortune.com/2025/12/02/how-anthropics-safety-first-approach-won-over-big-business-and-how-its-own-engineers-are-using-its-claude-ai/) sobre como eles usam o Claude, os engenheiros relataram usá-lo para cerca de 60% de suas tarefas de trabalho. As utilizações mais comuns? Depurar código existente, compreender o que partes da base de código estavam a fazer e implementar novas funcionalidades. Os engenheiros afirmaram que tendem a entregar ao Claude tarefas que "não são complexas, repetitivas, em que a qualidade do código não é crítica". E 27% do trabalho que agora fazem com o Claude simplesmente não teria sido feito antes.

Esta é a própria equipa da Anthropic. As pessoas que construíram o modelo estão a usá-lo como um leitor de documentação, um navegador de base de código e um gerador de primeiro rascunho. Todos os outros estão a fazer o mesmo, apenas com os seus documentos em vez dos deles.

A Anthropic foi deliberada em chamar isso de persona "construtora". As suas ferramentas foram concebidas não apenas para engenheiros de software profissionais, mas para qualquer pessoa que consiga descrever o que pretende construir. Quando Claude pode criar uma aplicação full-stack a partir de um design Figma via MCP, a linha tradicional entre "desenvolvedor" e "não desenvolvedor" se dissolve.

Isso tem implicações reais para qualquer pessoa que mantenha documentação ou se preocupe com a experiência do desenvolvedor. O seu público já não se limita às pessoas que sabem o que é um ponto de extremidade REST. Ele inclui qualquer pessoa cujo assistente de IA possa interagir com seu produto. O PM da Ramp que envia um recurso usando sua API? Provavelmente nunca lerá a sua documentação diretamente. O agente de IA deles lerá com certeza.

O que isso significa para a documentação

Se a documentação serve agora dois públicos, leitores humanos e intermediários de IA, precisa de funcionar para ambos. Parece óbvio. Na prática, quase ninguém o faz.

Eis o que eu acho que realmente importa:

**Se os documentos da sua API são uma página HTML lindamente renderizada que um LLM tem que raspar e analisar, a IA está a trabalhar mais do que deveria. Envie a especificação OpenAPI em bruto juntamente com a versão renderizada. Enviar markdown limpo. Tornar as especificações acessíveis sem exigir que a IA interprete o layout da página.

**Estrutura ao nível do bloco em vez de narrativa ao nível da página. Os assistentes de IA não consomem documentação página a página. Extraem as secções relevantes. Um documento com títulos claros, parágrafos autónomos e semântica explícita ao nível do bloco é muito mais útil para uma IA do que uma narrativa fluida que requer a leitura de toda a página para obter o contexto.

**Quando é que este documento foi revisto pela última vez? Ainda é atual? O conteúdo foi assinalado? Estes sinais têm de existir numa forma a que a IA possa aceder, e não apenas como sinais visuais numa página Web. Uma pontuação de atualidade, um estado de expiração, uma data de revisão, são os metadados que permitem a uma IA decidir se um documento é seguro para ser utilizado como fonte.

**Quando um assistente de IA fornece a um construtor uma resposta confiante baseada num ponto final obsoleto, os danos são piores do que um 404. O construtor constrói sobre ele. Faz o envio. Depois, ele quebra na produção e ninguém sabe o motivo até que alguém rastreie a documentação que deveria ter sido atualizada meses atrás. Cada documento que uma IA possa referenciar precisa de um mecanismo para provar que ainda está atualizado. (Isto é, revelação completa, exatamente o problema que estamos a construir para resolver com o Rasepi. Forçar a expiração de blocos de documentação para que o conteúdo obsoleto não se possa esconder).

Começando: audite sua documentação atual

Se leu até aqui e está a pensar "ok, mas o que é que eu faço na segunda-feira?", aqui estão quatro coisas concretas que pode verificar esta semana.

**1. Abra o Claude ou o ChatGPT e peça-lhe para integrar o seu produto num cenário realista. Não utilize os seus conhecimentos internos. Veja apenas o que a IA produz. Está correto? Está actualizada? Está a utilizar os pontos finais corretos, a versão correta do SDK, o fluxo de autenticação correto? Se a IA estiver errada, é isso que os construtores estão a receber neste momento.

**2. Escolha as cinco páginas de documentação mais visitadas e pergunte: quando foi a última revisão? Ainda descreve o estado atual do produto? Se não conseguir responder a esta pergunta com confiança, a IA também não conseguirá. Esta é a correção mais importante para a maioria das equipas.

3. Envie formatos legíveis por máquina Se você não tem um arquivo /llms.txt, crie um. Se a sua referência de API estiver disponível apenas como HTML renderizado, exporte a especificação OpenAPI bruta e torne-a acessível. Se os seus documentos estão num CMS que não produz markdown limpo, esse é um problema que vale a pena resolver agora.

4. Adicione datas de revisão e metadados de atualização. Mesmo algo simples, um campo last-reviewed em seu sistema de gerenciamento de conteúdo, um ciclo de revisão obrigatório para páginas de alto tráfego. Isto dá aos humanos e à IA um sinal sobre se o conteúdo é fiável. Ferramentas como o Rasepi podem automatizar isto com expiração forçada ao nível do bloco, mas mesmo um processo manual é melhor do que nada.

A mudança silenciosa na forma como os produtos são representados

Há uma consequência mais ampla de tudo isto que vale a pena referir diretamente.

A sua documentação já não é apenas um manual de referência para os programadores. É o material de origem que os assistentes de IA utilizam para representar o seu produto para o mundo. Quando um construtor pergunta ao Claude como utilizar o seu produto, a resposta do Claude é moldada por tudo o que consegue encontrar e analisar na sua documentação.

Bons documentos, boa resposta. Desactualizados, ambíguos, fechados em HTML que é difícil de analisar por um modelo? Pior resposta, ou uma resposta incorrecta. Tão simples quanto isso.

A qualidade da resposta da IA sobre o seu produto é agora um indicador direto da experiência do programador. A maioria das empresas ainda não está a tratar isso dessa forma.

As equipas que estão à frente nesta matéria, Stripe, Vercel, Cloudflare, Anthropic, tratam a legibilidade da IA como uma preocupação de primeira classe. Um requisito fundamental que molda a forma como a documentação é escrita, estruturada e mantida. Não é um item do backlog para o próximo trimestre.

O construtor sentado no Claude neste momento, descrevendo o que quer construir, esperando um código funcional em minutos. Talvez nunca mais volte a visitar um sítio de documentação. Mas a IA que os serve fá-lo-á. Constantemente.

Essa IA é agora o seu leitor mais frequente. A questão é saber se os seus documentos estão preparados para isso.

A melhor estratégia de experiência do programador em 2026 não é uma palestra numa conferência ou um guia de início rápido. É garantir que a IA o faz corretamente.

Este post faz referência a pesquisas e documentação de produtos disponíveis publicamente. As estatísticas são extraídas do Inquérito aos programadores do GitHub de 2024, do Inquérito aos programadores do Stack Overflow de 2024, do Relatório de produtividade dos programadores do Index.dev de 2026, das Estatísticas da Incremys Claude e do Relatório da Fortune sobre o Anthropic. A especificação /llms.txt é mantida em llmstxt.org. O Protocolo de Contexto de Modelo está documentado em modelcontextprotocol.io.

Como as traduções do Rasepi realmente funcionam e por que elas soam como a sua equipe

2026-03-31T00:00:00Z

Se alguma vez passou um documento pelo Google Translate ou, honestamente, por qualquer ferramenta de tradução, conhece o resultado. Tecnicamente correto. Tonalmente errado. De repente, o seu produto passa a chamar-se algo diferente. A abreviatura interna da sua equipa desaparece. "Você" formal onde a sua empresa usa informal, ou o contrário.

O resultado é traduzido, mas não soa a si.

Foi para isso que criei o sistema de tradução do Rasepi. Não é "podemos traduzir documentação" (todas as ferramentas podem fazer isso agora) mas "podemos traduzi-la para que soe como a nossa equipa a escreveu".

A resposta é sim. E não é necessária uma equipa de tradutores profissionais para o conseguir.

Traduções que soam como a sua equipa](/pt/blog/img/natural-translations.svg)

Só o que mudou é traduzido

A maioria das plataformas de documentação traduzem páginas inteiras. Altera-se uma frase e todo o documento vai para a retradução. Cada língua, cada parágrafo, quer tenha sido alterado ou não.

O Rasepi funciona de forma diferente. Acompanha cada parágrafo individualmente. Quando se edita uma secção de um documento de 20 secções, apenas essa secção é retraduzida. As outras 19, em todas as línguas, permanecem exatamente como estavam.

Isto significa duas coisas:

**Os seus custos de tradução baixam drasticamente. Estamos a falar de 94% menos para edições típicas. A maior parte das actualizações toca uma ou duas secções, não a página inteira.
**Se a sua equipa alemã aprovou uma tradução na semana passada, editar um parágrafo não relacionado em inglês não afectará o texto aprovado.

O sistema sabe o que mudou porque cada parágrafo tem uma identidade única e uma impressão digital do conteúdo. Quando a impressão digital muda, esse parágrafo específico é assinalado para retradução. Nada mais.

O seu glossário, a sua terminologia

É aqui que as coisas ficam interessantes.

Cada empresa tem o seu próprio vocabulário. "Sprint Review" pode ficar como "Sprint Review" nos seus documentos em alemão porque a sua equipa de Berlim usa o termo em inglês. Ou pode tornar-se "Sprint-Überprüfung" porque a sua equipa de Munique prefere a versão alemã. "Knowledge Base" pode ser "Wissensdatenbank" ou "Knowledge Base" ou algo completamente diferente que a sua equipa cunhou internamente.

O Rasepi permite-lhe criar um glossário para cada língua. Basicamente, uma lista de termos e as suas traduções aprovadas. Quando um parágrafo é traduzido, o sistema verifica primeiro o seu glossário. Cada termo da sua lista é traduzido exatamente da forma como o definiu. Sempre. Em todos os documentos.

Pode gerir o seu glossário diretamente no Rasepi:

Adicionar termos um a um à medida que se apercebe de inconsistências
Importar um CSV** se já tiver uma lista de terminologia de outro sistema
Exportar o seu glossário** para partilhar com tradutores externos ou outras ferramentas

O glossário funciona por par de línguas. O seu glossário de inglês para alemão é separado do seu glossário de inglês para francês. Isto é importante porque o mesmo termo em inglês pode precisar de um tratamento diferente em diferentes idiomas. "Sprint Review" pode permanecer em inglês em alemão, mas ser traduzido em japonês.

Quando actualiza o seu glossário, a alteração entra em vigor na próxima vez que um parágrafo for traduzido para esse idioma. Não há necessidade de retraduzir tudo manualmente. O próximo ciclo de edição natural apanha-o.

Regras de estilo: fazer com que as traduções soem como se as tivesse escrito

Os glossários tratam de palavras individuais. Mas uma tradução pode usar todos os termos corretos e ainda assim parecer estranha. Tom incorreto. Datas no formato errado. Números com o separador errado. Símbolos de moeda no sítio errado.

É para isso que servem as regras de estilo.

Para cada língua, pode configurar um conjunto de regras que controlam a forma como as traduções são formatadas:

Convenções de formatação

Estes são os detalhes que fazem um documento parecer nativo em vez de "obviamente traduzido do inglês":

** Formatos de data e hora: relógio de 24 horas para o alemão, AM/PM para o inglês, etc.
Formatação de números: vírgula como separador decimal em alemão (3,14 em vez de 3,14), ponto final para milhares
Regras de pontuação: formatação de graus académicos, estilos de aspas e outras convenções regionais

O utilizador escolhe as convenções que correspondem aos padrões da sua empresa. O Rasepi aplica-as a todas as traduções nessa língua, em todos os documentos.

Instruções personalizadas

É aqui que as coisas ficam realmente poderosas. As instruções personalizadas são diretivas em linguagem simples que dizem ao motor de tradução como lidar com o seu conteúdo. Escreve-as em frases normais e o motor segue-as.

Alguns exemplos:

"Use um tom amigável e diplomático " para uma empresa que quer uma documentação acessível
"Utilize sempre a forma formal 'Sie', nunca 'du'" para uma comunicação alemã profissional
"Utilize a ortografia do inglês britânico: colour, organisation, licence " quando o seu público de língua inglesa vive no Reino Unido
"Coloque símbolos de moeda após o valor numérico " para corresponder às convenções europeias
"Ao descrever os pontos finais da API, utilize o modo imperativo " para documentos técnicos que devem ser diretos

Pode adicionar até 200 instruções personalizadas por idioma. Funcionam juntamente com o seu glossário e regras de formatação, e o motor de tradução considera-as todas em conjunto em cada tradução.

Formalidade

O alemão tem "du" e "Sie". O francês tem "tu" e "vous". O japonês tem vários níveis de polidez. Mesmo as línguas sem pronomes formais/informais óbvios têm diferenças tonais que são importantes.

O Rasepi permite-lhe definir o nível de formalidade para cada língua. Uma vez configurado, cada parágrafo traduzido corresponde a esse tom. Se a sua empresa se dirige aos leitores formalmente em francês ("vous") mas informalmente em alemão ("du"), é exatamente isso que cada tradução fará.

Tudo funciona em conjunto

Eis o que importa: os termos do glossário, as convenções de formatação, as instruções personalizadas e as definições de formalidade aplicam-se a todas as traduções ao mesmo tempo. Não se escolhe um ou outro. Configura-os todos uma vez, e cada parágrafo que é traduzido passa pelo mesmo conjunto de regras.

O resultado são traduções que se lêem como se alguém da sua equipa local as tivesse escrito. Não como uma máquina que traduziu cada frase sem saber nada sobre a sua empresa.

Cada língua pode ter o seu próprio conteúdo

Esta é a caraterística que mais surpreende as pessoas.

No Rasepi, um documento traduzido não é uma cópia bloqueada do original. Cada versão linguística pode ter conteúdos que só existem nessa língua.

**Porque é que isto é importante?

Porque mercados diferentes precisam de coisas diferentes:

A sua documentação alemã pode precisar de uma secção de conformidade com o DSGVO (GDPR) que não se aplica à versão americana
A sua equipa japonesa pode precisar de uma nota sobre as ferramentas locais que mais ninguém utiliza
O seu escritório no Brasil pode precisar de contexto sobre regulamentos fiscais regionais

Na maioria das ferramentas de tradução, adicionar conteúdo a uma versão linguística significa que é substituído na próxima vez que alguém retraduzir do inglês. As equipas percebem isso rapidamente e param de adicionar conteúdo local. Criam documentos sombra no Notion, no Slack ou noutro sítio qualquer, e agora tem dois sistemas em que ninguém confia totalmente.

No Rasepi, o conteúdo único é assinalado como pertencente a essa língua. Nunca é substituído por uma retradução. Nunca é apagado quando a fonte inglesa muda. Vive ao lado do conteúdo traduzido como uma parte natural do documento.

O mesmo se aplica à estrutura. Se os seus tradutores japoneses preferirem listas numeradas onde a versão inglesa utiliza marcadores (uma convenção comum na escrita técnica japonesa), podem alterar o formato. O Rasepi preserva essa escolha em futuras actualizações.

Cada versão linguística é um documento de primeira classe, não um espelho só de leitura.

Automático e humano: trabalham em conjunto

O Rasepi não o obriga a escolher entre a tradução automática e a tradução humana. Ele suporta ambas e sabe a diferença.

Quando um parágrafo é traduzido por máquina e a fonte muda, o Rasepi retraduz-o automaticamente. Não é necessária qualquer intervenção humana. O glossário e as regras de estilo mantêm a coerência.

Quando um parágrafo foi editado manualmente por um tradutor humano, talvez para lhe dar um toque cultural ou acrescentar um contexto que uma máquina não apanharia, o Rasepi respeita esse trabalho. Se a fonte for alterada, o sistema assinala o parágrafo como necessitando de revisão mas nunca substitui silenciosamente as edições humanas. O tradutor vê o que mudou na fonte e decide como atualizar a sua versão.

Isto significa que a qualidade da sua tradução melhora com o tempo. A tradução automática trata da maior parte do texto. Os tradutores humanos concentram-se nos parágrafos que precisam de um toque humano. E nenhum dos dois pisa o trabalho do outro.

Dois modos: sempre atual ou traduzir a pedido

Para cada língua, pode escolher quando as traduções são efectuadas:

Sempre que alguém salva o documento de origem, os parágrafos alterados são retraduzidos imediatamente. Melhor para os idiomas mais importantes, onde os leitores esperam uma precisão actualizada.
Traduzir quando visualizado.** Os parágrafos alterados são assinalados mas não são traduzidos até que alguém abra efetivamente o documento nessa língua. Ótimo para as línguas que são utilizadas com menos frequência. Sem custos de tradução desperdiçados em conteúdo que ninguém está a ler.

Ambos os modos utilizam o mesmo glossário, as mesmas regras de estilo, a mesma qualidade. A única diferença é o tempo.

O que isto parece na prática

Imagine que dirige uma empresa com equipas em Londres, Munique, Paris e Tóquio. A sua documentação está escrita em inglês.

Um gerente de produto em Londres atualiza o guia de implantação. Uma secção sobre um novo passo de CI/CD.

O que acontece é o seguinte:

A secção alterada é retraduzida em segundos. "Sprint Review" torna-se "Sprint-Überprüfung" porque isso está no seu glossário. Formal "Sie" porque é a sua definição de formalidade. Datas em formato de 24 horas porque essa é a sua regra configurada. A instrução habitual "use um tom direto e imperativo" molda o fraseado. A secção DSGVO que a equipa de Munique acrescentou? Intocada.
A mesma secção, retraduzida imediatamente. Formalidade "Vous". Termos do glossário francês aplicados. Símbolos de moeda após o número de acordo com as suas instruções personalizadas. O resto do documento mantém-se exatamente como o escritório de Paris o reviu pela última vez.
A secção alterada é assinalada como obsoleta. Quando alguém em Tóquio abre o documento, ele é traduzido na hora. A formatação personalizada da lista de números é preservada. A nota de ferramenta local permanece no lugar.

Uma edição. Três idiomas actualizados. Zero retraduções de documentos completos. Terminologia consistente, tom consistente e respeito pelas adições locais de cada equipa.

Por falar em qualidade da língua

O motor de tradução que está por detrás de tudo isto é o DeepL, a mesma tecnologia que alimenta a funcionalidade Talk to Docs do Rasepi. Pode falar com a sua documentação e obter respostas em voz alta. O DeepL Voice trata da interação falada, o que significa que a mesma consistência terminológica, regras de estilo e qualidade linguística que obtém nas traduções escritas também se aplica às conversas por voz. Os termos do seu glossário e as instruções personalizadas soam bem, quer a sua equipa esteja a ler ou a ouvir.

As traduções que soam como a sua equipa não são um luxo. Para as empresas que operam em vários idiomas, elas são a diferença entre a documentação em que as pessoas confiam e a documentação que as pessoas contornam. Glossários, regras de estilo, instruções personalizadas, retradução inteligente e conteúdo exclusivo por idioma tornam isso possível. Automaticamente, desde o primeiro dia.

A sua documentação deve soar como a sua equipa em todas as línguas. Não como uma máquina. Não como uma empresa diferente. Como você.

Veja a publicação multilingue em ação →

Por dentro do mecanismo de tradução: Glossários, Regras de Estilo e Retradução Inteligente

2026-03-31T00:00:00Z

O nosso post de arquitetura anterior cobriu plugins, guardas de ação e o sistema de pipeline. Este vai mais fundo no motor de tradução, a parte que eu acho que torna o Rasepi fundamentalmente diferente de qualquer outra plataforma de documentação.

Não é o discurso de marketing sobre traduzir parágrafos em vez de páginas. O código real. Como os glossários são resolvidos por locatário, como as regras de estilo do DeepL e as instruções personalizadas moldam cada tradução, como o hashing de conteúdo impulsiona a deteção de desatualização e como o orquestrador decide quais blocos devem ser retraduzidos.

A linha de tradução

Quando um utilizador guarda um documento, o sistema não se limita a retraduzir tudo. Ele executa uma sequência bastante específica:

Analisa o JSON do TipTap em blocos individuais
Compara hashes de conteúdo para detetar quais blocos foram realmente alterados
Para blocos alterados, resolver o glossário do locatário e a lista de regras de estilo para o par de idiomas
Aplicar regras de estilo, instruções personalizadas e formalidade da configuração do locatário
Enviar apenas blocos modificados para DeepL
Atualizar os blocos de tradução e sincronizar os hashes de conteúdo

Cada passo é o seu próprio serviço com a sua própria interface. Isso é importante porque qualquer etapa pode ser trocada por outra coisa, um fornecedor de tradução diferente, um algoritmo de hashing diferente, uma fonte de glossário diferente.

Resolução do glossário: com escopo do locatário, sincronizado com DeepL

DeepL glossários têm uma restrição que a maioria das pessoas não conhece: eles são imutáveis. Você não pode editar um glossário DeepL. Qualquer mudança significa apagar o antigo e criar um novo.

O Rasepi lida com isto tratando a base de dados como a fonte da verdade e os DeepL glossários como artefactos descartáveis em tempo de execução. A entidade TenantGlossary armazena tudo 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; }
}

Quando um utilizador adiciona uma entrada no glossário, por exemplo, mapeando "Sprint Review" para "Sprint-Überprüfung" para EN→DE, o registo da base de dados é atualizado imediatamente e IsDirty é definido para true. O glossário DeepL não é recriado imediatamente. Ele é recriado preguiçosamente, na próxima vez que uma tradução realmente precisar dele.

O fluxo de sincronização

Antes de cada chamada de tradução, o sistema resolve o glossário:

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;
}

Três coisas dignas de nota aqui:

Sincronização preguiçosa Nós só acessamos a API DeepL quando uma tradução é realmente necessária. A edição de entradas do glossário em massa não desencadeia dezenas de chamadas à API.
**A consulta é executada através de filtros de consulta global EF, então TenantGlossaries é automaticamente escopo. As entradas do glossário do locatário A nunca entram nas traduções do locatário B.
Um glossário por par de línguas DeepL impõe isto de qualquer forma. Um glossário EN→DE, um glossário EN→FR, e assim por diante. O par (SourceLanguage, TargetLanguage) é único por locatário.

Entradas do glossário

As entradas individuais são apenas mapeamentos de termos:

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"
}

A API oferece-lhe CRUD completo e importação/exportação de CSV para gestão em massa:

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

A importação de CSV é muito útil para equipas que migram de sistemas de memória de tradução existentes. Exporte os seus termos, limpe-os, importe-os para o Rasepi, e a próxima tradução usa o novo glossário automaticamente.

Regras de estilo, instruções personalizadas e formalidade

Os glossários tratam da terminologia. Mas a terminologia é apenas metade da questão. Uma tradução pode usar todas as palavras corretas e mesmo assim soar mal. Tom errado, formato de data errado, convenções de pontuação erradas.

A ** API de regras de estilo** (v3) do DeepL resolve este problema. É possível criar listas de regras de estilo reutilizáveis que combinam dois tipos de controlos:

Regras configuradas, convenções de formatação predefinidas para datas, horas, pontuação, números e muito mais
Instruções personalizadas, diretivas de texto livre que moldam o tom, o fraseado e as convenções específicas do domínio

O Rasepi cria e gere estas instruções por inquilino, por idioma de destino. A entidade TenantStyleRuleList armazena o DeepL style_id juntamente com as regras configuradas e as instruções personalizadas do locatário:

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; }
}

Criar listas de regras de estilo

Quando um administrador define regras de tradução para alemão, o Rasepi chama a API v3 do DeepL para criar a lista de regras de estilo. Aqui está o 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;
}

Ao contrário dos glossários, as listas de regras de estilo do DeepL são mutáveis. Pode substituir as regras configuradas no local com PUT /v3/style_rules/{style_id}/configured_rules, e as instruções personalizadas podem ser adicionadas, actualizadas ou eliminadas individualmente. Muito mais amigável para refinamento iterativo.

Como são as regras configuradas

As regras configuradas cobrem convenções de formatação que variam de acordo com o idioma ou preferência da empresa. Coisas 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"
  }
}

Estas regras parecem triviais, mas são muito rápidas. Um documento alemão que usa o formato de hora AM/PM e decimais separados por ponto final é lido como "traduzido do inglês" para um leitor alemão. Definir use_24_hour_clock e use_comma para separadores decimais em todas as traduções alemãs elimina isso imediatamente.

Instruções personalizadas: este é o verdadeiro poder

As instruções personalizadas são diretivas de texto livre, até 200 por lista de regras de estilo, cada uma com um máximo de 300 caracteres. Basicamente, diz a DeepL como moldar a tradução em linguagem simples:

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
}

Exemplos reais dos nossos inquilinos:

"Use a friendly, diplomatic tone" para uma empresa em fase de arranque que pretende documentos acessíveis
"Always use 'Sie' form, never 'du'" para um escritório de advogados alemão
"Translate 'deployment' as 'Bereitstellung', never 'Deployment'" para termos que necessitam de tratamento dependente do contexto para além do simples mapeamento do glossário
"Use British English spelling (colour, organisation, licence)" para empresas sediadas no Reino Unido que traduzem entre variantes do inglês
"Put currency symbols after the numeric amount" para corresponder às convenções europeias

As instruções personalizadas são realmente poderosas para convenções específicas do domínio que não cabem nas entradas do glossário. Um glossário mapeia um termo para outro. Uma instrução personalizada pode dizer "ao traduzir documentos API, use o modo imperativo em vez da voz passiva". Trata-se de um tipo de controlo completamente diferente.

Formalidade

O parâmetro formality de DeepL (default, more, less, prefer_more, prefer_less) ainda está disponível como um controlo separado juntamente com as regras de estilo. Alemão "du" versus "Sie", francês "tu" versus "vous", níveis de polidez japoneses. Estes são definidos por idioma do locatário atravé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; }
}

A formalidade, as regras de estilo e os glossários são todos compostos. Uma única chamada de tradução pode conter todos os três:

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"
};

Duas coisas que vale a pena notar aqui:

**Passamos blocos adjacentes como contexto para melhorar a qualidade da tradução. DeepL usa-o para resolver ambiguidades, mas não o traduz nem o fatura. Um parágrafo sobre "células" é traduzido de forma diferente quando o contexto circundante é um documento de biologia versus um manual de folha de cálculo.
**Seleção do modelo Qualquer pedido com style_id ou custom_instructions utiliza automaticamente o modelo quality_optimized de DeepL. Este é o nível de qualidade mais elevado. Não é possível combiná-los com latency_optimized, o que é uma restrição deliberada de DeepL. A personalização do estilo necessita do modelo completo.

Porque é que isto é mais importante do que se pensa

Imagine uma empresa que escreve documentos internos em alemão com o informal "du" que subitamente muda para o formal "Sie" numa secção traduzida. Parece inconsistente, na melhor das hipóteses, e pouco profissional, na pior. A formalidade trata disso. Mas a formalidade, por si só, não vai apanhar um documento que usa carimbos de data e hora AM/PM quando o seu escritório alemão usa o formato de 24 horas, ou que coloca o símbolo da moeda antes do número em vez de depois.

Todos estes elementos em conjunto (regras de estilo, instruções personalizadas, formalidade, glossários) produzem traduções que parecem ter sido escritas por alguém da sua equipa. Não como se fossem produzidas por uma máquina que não sabe que a sua empresa existe.

A camada de serviço DeepL

Toda a comunicação DeepL passa pelo IDeepLService. Ele envolve o SDK oficial do DeepL .NET e lida com as chamadas da API v3 para regras 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();
}

A implementação trata da normalização do código da língua. DeepL requer EN-US ou EN-GB em vez de en simples, e PT-PT ou PT-BR em vez de pt:

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

A tradução em lote usa 50-item chunking para ficar dentro dos limites da API do DeepL enquanto maximiza a taxa de transferência:

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
    };
}

Como só enviamos blocos obsoletos, e não documentos inteiros, um lote de tradução típico para uma única edição contém 1-3 blocos em vez de mais de 40. É daí que vem a redução de custos de 94%.

O orquestrador de tradução

O TranslationOrchestrator decide o que fazer com cada bloco quando o documento de origem é alterado. Vamos percorrer a árvore de decisão:

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);
}

A parte chave: **Se um tradutor ajustou manualmente um bloco, talvez adicionando contexto cultural ou reformulando a redação para maior clareza, o sistema respeita esse trabalho. Marca o bloco como obsoleto para que o tradutor saiba que a fonte mudou, mas não substitui silenciosamente as suas edições.

Blocos traduzidos por máquina com AlwaysTranslate ativado são retraduzidos imediatamente. Os blocos traduzidos automaticamente com TranslateOnFirstVisit são marcados como obsoletos e traduzidos quando alguém abre efetivamente o documento nessa língua.

Gatilhos de tradução: quando as traduções acontecem

Cada língua tem um TranslationTrigger que controla o tempo:

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

O AlwaysTranslate é útil para línguas de alta prioridade onde quer que as traduções sejam imediatamente actuais. Francês para uma empresa com um grande escritório em Paris. Alemão para uma empresa com sede em Munique.

TranslateOnFirstVisit é útil para línguas que são ocasionalmente necessárias, mas que não valem o custo da API para manter perfeitamente actualizadas em todos os momentos. Quando alguém abre o documento nessa língua, os blocos obsoletos são traduzidos em tempo real.

Ambos os modos usam a mesma resolução de glossário, as mesmas configurações de formalidade e o mesmo hashing de conteúdo. A única diferença é o tempo.

Adaptação única de conteúdo e estrutura

É aqui que a arquitetura compensa realmente, para além da simples tradução.

Quando um tradutor alemão adiciona uma secção de conformidade DSGVO que não existe em inglês, adiciona-a como um novo bloco na versão alemã. Esse bloco não tem SourceBlockId, é assinalado como conteúdo único. O sistema nunca o envia para retradução porque não existe uma fonte a partir da qual traduzir. Só existe em alemão.

Quando um tradutor japonês muda uma lista de marcadores para uma lista numerada (uma convenção comum na escrita técnica japonesa), a marca IsStructureAdapted do bloco preserva-o em futuros ciclos de retradução:

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,
};

O sinalizador IsNoTranslate lida com o conteúdo que deve ser copiado literalmente: blocos de código, URLs, nomes de produtos, notação matemática. O fornecedor de tradução ignora-os completamente.

Colocando tudo junto

Vamos percorrer o fluxo completo. Um utilizador em Londres edita um parágrafo no documento de origem em inglês e o seu escritório em Munique tem o alemão definido como AlwaysTranslate:

**O utilizador guarda. O TipTap envia JSON para a API.
**O CreateBlocksFromDocumentAsync analisa o JSON, recalcula os hashes de conteúdo e compara os hashes antigos e novos para identificar os blocos que foram efetivamente alterados.
**Encontra o EntryTranslation alemão e verifica o bloco alemão. É traduzido por máquina, não está bloqueado, não foi editado por humanos, por isso é elegível para retradução.
**Configuração de tradução carregada: ID do glossário resolvido através de GetOrSyncDeepLGlossaryIdAsync("en", "de"), regras de estilo através de GetOrSyncStyleRuleListAsync("de"), formalidade definida para "more" (formal "Sie"), blocos adjacentes passados como contexto para desambiguação.
Chamada DeepL Bloco único enviado com ID do glossário, ID do estilo, formalidade e contexto.
Bloco atualizado. Conteúdo traduzido armazenado, SourceContentHash sincronizado, estado definido para UpToDate. Um bloco traduzido em vez de 40+. Os restantes 39 blocos? Inalterados.

Entretanto, o seu escritório de Tóquio tem o japonês definido para TranslateOnFirstVisit. A mesma edição marca o bloco de tradução em japonês como Stale. Quando alguém em Tóquio abre o documento, os passos 5-9 acontecem na hora. A adaptação da sua estrutura (lista numerada) é preservada. Os seus blocos únicos permanecem exatamente onde estão.

Penso que o motor de tradução é a parte do Rasepi que oferece o valor mais visível. As traduções que utilizam a sua terminologia, seguem as suas convenções de formatação, obedecem às suas instruções personalizadas, correspondem ao seu tom, respeitam o trabalho dos seus tradutores e custam uma fração do que custaria a retradução de um documento completo. A arquitetura torna tudo isto automático e mantém-se fora do caminho quando os humanos querem assumir o controlo.

O mesmo motor DeepL que alimenta as traduções escritas também alimenta o Talk to Docs, a nossa interface de documentação conversacional, com o DeepL Voice a tratar da interação falada. Os mesmos glossários, as mesmas regras de estilo, a mesma formalidade, a mesma consistência. Quer a sua equipa leia a documentação ou fale com ela, a qualidade da linguagem é idêntica.

Explore a API de tradução →

Pare de manter cinco cópias do mesmo documento

2026-03-31T00:00:00Z

Abra a wiki da sua empresa agora mesmo e pesquise por "onboarding". Quantos resultados obtém?

Se for uma empresa global, acho que não é um só. Provavelmente é algo como isto:

BLOQUEIO DE CÓDIGO_0
BLOQUEIO DE CÓDIGO_1
Onboarding Guide - Japan
Onboarding LATAM (draft)
BLOQUEIO DE CÓDIGO_4

Cinco documentos. Todos cobrem mais ou menos a mesma coisa. Todos ligeiramente diferentes. Todos mantidos por pessoas diferentes em horários diferentes. Alguns actuais, outros com três meses de atraso, um de que já ninguém tem a certeza.

Isto é o que acontece quando a sua plataforma de documentação não consegue lidar corretamente com conteúdos multilingues. Acaba por copiar todo o documento para cada mercado, e cada cópia afasta-se lentamente das outras.

A armadilha de copiar e localizar

Começa de forma bastante inocente. Tem um ótimo guia de integração em inglês. O escritório de Berlim precisa dele em alemão, por isso alguém o copia, traduz e acrescenta as partes específicas da Alemanha: Formação DSGVO, informação Betriebsrat, inscrição no seguro de saúde local.

Depois, Tóquio precisa de um. Copiar de novo. Traduzir. Acrescentar as informações específicas do Japão: registo no hanko, processo de obtenção do passe de transportes públicos, guia de etiqueta do escritório.

Segue-se São Paulo. A mesma coisa. Copiar, traduzir, adicionar conteúdo local sobre os requisitos do CLT, vales de refeição e documentos fiscais.

Agora tem quatro documentos. O original em inglês é atualizado regularmente. A versão alemã foi actualizada no último trimestre. A versão japonesa... alguém pensa que Tanaka-san a actualizou em outubro. A versão brasileira foi criada por um empreiteiro que saiu e, desde então, ninguém lhe tocou.

**Cada cópia é um fardo de manutenção e cada uma delas contém uma mistura de conteúdo partilhado (o que é igual em todo o lado) e conteúdo local (o que é específico desse mercado). Mas a plataforma não sabe a diferença. É tudo apenas texto numa página.

Assim, quando alguém actualiza a secção da política de segurança no original em inglês, ninguém actualiza as outras quatro. Ou pior, alguém actualiza a secção alemã mas não a japonesa. Agora tem cinco documentos que dizem coisas ligeiramente diferentes sobre a mesma política da empresa.

O verdadeiro problema: os conteúdos partilhados e locais estão misturados

O facto é que a maioria destes documentos são 70-80% idênticos. Os passos de integração, a configuração das ferramentas, as políticas de segurança, a secção de valores da empresa, a lista de "quem contactar". Tudo isto é igual, independentemente de estarmos em Berlim, Tóquio ou São Paulo.

Os aspectos locais representam talvez 20-30% do documento. Requisitos de conformidade específicos, benefícios locais, processos regionais, contactos da equipa para esse escritório.

Mas quando tudo está num grande documento plano por língua, não há forma de saber que partes são partilhadas e quais são locais. Uma atualização do conteúdo partilhado implica a verificação e atualização manual de todas as cópias. O que ninguém faz de forma consistente. É por isso que as cópias se desviam.

Um documento. É só isso.

No Rasepi, o guia de integração é um documento. Não um por língua. Um.

O conteúdo partilhado, os 70-80% que são iguais em todo o lado, é escrito uma vez em inglês e traduzido automaticamente para todas as línguas que a sua equipa utiliza. Quando alguém actualiza a secção da política de segurança em inglês, esta é retraduzida para alemão, japonês, português e francês em segundos. Sem cópia manual. Nada de "alguém deve atualizar as outras versões".

O conteúdo local reside na respectiva versão linguística. A secção de formação DSGVO existe apenas na versão alemã. O processo hanko existe apenas na versão japonesa. Os requisitos do TTC existem apenas na versão portuguesa. Estas secções estão assinaladas como conteúdo único, pertencem a essa língua e nunca são substituídas por retradução.

Explicámos exatamente como isto funciona no nosso post sobre como funcionam as traduções da Rasepi. A versão resumida: cada parágrafo tem a sua própria identidade. Os parágrafos partilhados são traduzidos e monitorizados. Os parágrafos únicos pertencem à sua língua e nada mais lhes toca.

O resultado? A sua pesquisa na wiki por "onboarding" apresenta um resultado. Apenas "Onboarding". Se o abrir em inglês, verá a versão inglesa com todo o conteúdo partilhado. Se abrir em alemão, verá o mesmo conteúdo partilhado em alemão e as secções específicas da Alemanha. Se abrir em japonês, vê o mesmo conteúdo partilhado em japonês e as secções específicas do Japão.

Um documento. Não cinco. Não cinco documentos a apodrecerem lentamente a velocidades diferentes.

O que isso realmente muda

Isto não é apenas mais arrumado. Altera fundamentalmente a forma como a sua documentação funciona em todos os escritórios.

As actualizações chegam a todos

Quando actualiza a parte partilhada do guia de integração, esta é actualizada em todas as línguas. Não eventualmente, nem depois de alguém se lembrar de o fazer. Automaticamente. O parágrafo que alterou é retraduzido. Tudo o resto permanece exatamente onde estava.

Isto significa que o escritório de Tóquio está a ler a mesma política da empresa que o escritório de Londres. Não a versão de há seis meses atrás que ninguém conseguiu atualizar.

As equipas locais são proprietárias dos seus conteúdos locais

A sua equipa de Munique pode adicionar uma secção sobre o desconto no ginásio local sem se preocupar com a possibilidade de ser eliminada pela próxima atualização em inglês. O seu conteúdo exclusivo é deles. Permanece na versão alemã, sem ser afetado por quaisquer alterações à fonte inglesa.

O mesmo se aplica a todos os outros escritórios. O conteúdo local é genuinamente local. Não interfere com os conteúdos partilhados, e os conteúdos partilhados não interferem com eles.

As novas contratações recebem a informação correta

Um novo contratado em São Paulo abre o guia de integração e vê tudo o que precisa. As secções partilhadas (ferramentas, segurança, valores) estão em português. As secções específicas do Brasil (CLT, documentos fiscais, vales de refeição) estão mesmo ao lado. Um documento, tudo na língua deles, nada em falta, nada desatualizado.

Não precisam de saber que três outros escritórios têm secções locais diferentes. Vêem apenas a sua versão. Limpa e completa.

O número de páginas diminui

Esta é a matemática simples. Se tiver 50 documentos-chave e os mantiver em 5 línguas com a abordagem copiar-e-localizar, tem 250 documentos. No Rasepi, tem 50. Cada um com versões linguísticas que partilham conteúdos comuns e mantêm as suas próprias secções locais.

250 documentos para manter versus 50. São 200 páginas de despesas gerais de manutenção que simplesmente desaparecem.

Não se trata apenas de integração

O onboarding é o exemplo óbvio porque todas as empresas globais têm este problema. Mas o mesmo padrão aparece em todo o lado:

Os passos principais são os mesmos, mas a equipa de Berlim utiliza um servidor de teste local e Tóquio tem um processo de aprovação diferente.
Documentação de conformidade: secção GDPR para a Europa, LGPD para o Brasil, APPI para o Japão. Tudo no mesmo documento, cada um aparecendo apenas onde é relevante.
Benefícios e políticas de RH: a política de licença parental é diferente em cada país. Os valores da empresa são os mesmos em todo o lado.
O produto funciona da mesma forma em todo o lado, mas os métodos de pagamento, as horas de apoio e os regulamentos regionais variam.

Cada um destes é um documento que a maioria das empresas mantém em cópias separadas por mercado. E cada um deles pode ser um único documento com conteúdo partilhado e local.

O efeito composto

É aqui que as coisas se tornam reais. Uma empresa com 200 documentos em 4 mercados não está a manter 200 documentos. Está a manter 800. Mas tem pessoal para 200. Portanto, o que acontece de facto é:

As versões em inglês estão actualizadas
As versões em alemão estão quase todas actualizadas
As versões francesas estão atrasadas
As versões japonesas são um ponto de interrogação

Parece-lhe familiar?

Na Rasepi, são actualizados 200 documentos. O conteúdo partilhado é traduzido automaticamente. O conteúdo local é adicionado pelas equipas locais. Cada versão é tão atual como a versão inglesa, acrescida de quaisquer adições locais que a equipa regional tenha feito.

Os custos de tradução também são mais baixos. Quando actualiza um parágrafo em inglês, apenas esse parágrafo é retraduzido em todas as línguas. Não o documento inteiro, nem todos os 200 documentos. Apenas o parágrafo que foi efetivamente alterado. Escrevemos sobre como isso funciona em pormenor, incluindo o glossário e as regras de estilo que fazem com que o conteúdo traduzido pareça natural.

Uma verificação rápida

Se estiver a gerir uma equipa global, pergunte a si próprio:

Quantos documentos duplicados tem? Pesquise o mesmo tópico e conte as cópias específicas de cada língua.
Quão actuais são as versões não inglesas? Verifique a data da última edição nos documentos em alemão, francês ou japonês. Quão atrasadas estão?
As equipas locais adicionam conteúdo às suas versões? Ou desistiram porque é substituído?
**Quanto tempo demora o onboarding nos escritórios que não falam inglês? Se demorar mais tempo, é provável que a documentação não esteja a ser devidamente utilizada.

Se as respostas o deixam desconfortável, não é o único. A maioria das empresas não se apercebe da sobrecarga que criou até contar efetivamente as cópias.

A documentação deve acompanhar a sua empresa e não multiplicar-se. Cada cópia que mantém é uma cópia que pode ficar para trás, confundir uma nova contratação ou contradizer a versão que outra pessoa está a ler. Um documento por tópico, com o conteúdo partilhado traduzido e o conteúdo local no seu devido lugar, é a forma como a documentação deve funcionar numa empresa global.

**A sua wiki não deve precisar de cinco cópias do mesmo documento. Uma é suficiente. Passos partilhados traduzidos, passos locais por língua. É só isso.

Veja a publicação multilingue em ação →

O caso de negócios para a localização em nível de bloco

2026-03-24T00:00:00Z

Existe um padrão em todas as empresas que operam além-fronteiras. A documentação em inglês é sólida. A versão alemã está três meses atrasada. A versão japonesa foi traduzida uma vez, por uma empresa contratada, e ninguém tocou nela desde então. A versão em português do Brasil ainda não existe, apesar de São Paulo ser o escritório que mais cresce.

Toda a gente concorda que isto é um problema. Ninguém tem uma boa solução. Até agora, a localização tem sido tratada como um projeto, um esforço único que se orçamenta, executa e depois se negligencia discretamente até à próxima grande revisão.

Esta abordagem está estragada. Eis porquê e o que eu penso que realmente funciona.

Tradução não é localização

Vamos esclarecer a terminologia. A tradução é pegar num texto numa língua e produzir um texto equivalente noutra. A localização é fazer com que o conhecimento funcione num mercado específico. Sobrepõem-se, mas não são a mesma coisa.

Um documento traduzido lê-se corretamente. Um documento localizado lê-se naturalmente. Tem em conta o contexto cultural, os regulamentos regionais, as ferramentas locais e a forma como as pessoas desse mercado trabalham efetivamente.

Esta distinção é importante porque a maioria das plataformas de documentação trata a localização como uma tarefa de tradução. Escreve-se em inglês, carrega-se num botão e obtém-se um resultado em francês. Está feito. Exceto que não está feito, porque:

A equipa francesa tem um processo de implementação diferente que o documento em inglês não cobre
Os requisitos de conformidade alemães acrescentam um passo de aprovação adicional que não existe noutros locais
O escritório japonês utiliza uma ferramenta interna diferente para o mesmo fluxo de trabalho
Os leitores do português do Brasil precisam de contexto sobre as regras fiscais locais que não são relevantes em mais lado nenhum

**Uma tradução direta do documento em inglês é tecnicamente correta em todos estes casos e praticamente inútil também em todos eles.

O problema da tradução ao nível do documento

A localização tradicional funciona ao nível do documento. Tem um documento em inglês. Traduz todo o documento para alemão. Quando a versão inglesa é alterada, envia-se o documento completo para retradução. Isto cria três problemas:

1. É caro

Se o seu guia de integração tiver 15 secções e alterar um parágrafo, estará a pagar para retraduzir todas as 15 secções. Multiplique isso por 8 idiomas e cada edição torna-se uma conversa de orçamento.

2. É lento

Enviar documentos completos para tradução leva tempo. Mesmo com a tradução automática moderna, o ciclo de revisão de um documento completo é significativamente mais longo do que a revisão de uma única secção alterada. As equipas noutras línguas estão sempre atrasadas.

3. Não suporta conteúdo exclusivo

Este é o verdadeiro problema. Se a versão alemã precisar de uma secção extra sobre a conformidade com a DSGVO, para onde vai? Num sistema de tradução ao nível do documento, qualquer conteúdo adicionado à versão alemã é substituído na próxima vez que alguém retraduzir a partir do inglês. A equipa alemã aprende depressa: não acrescente nada, porque será apagado.

Localização ao nível do bloco: uma arquitetura diferente

O Rasepi não traduz documentos. Traduz blocos: parágrafos individuais, cabeçalhos e secções, cada um deles rastreado de forma independente com a sua própria identidade e hash de conteúdo.

Eis o que isto significa na prática:

Quando edita um único parágrafo em inglês, o Rasepi detecta qual o bloco que foi alterado através da comparação de hashes de conteúdo SHA256. Apenas esse bloco é enviado para tradução via DeepL. Os outros 14 blocos do documento permanecem exatamente como estavam. O seu custo de tradução diminui até 94%.

Quando o tradutor alemão precisa de acrescentar uma secção DSGVO, acrescenta-a como um novo bloco na versão alemã. Esse bloco existe apenas em alemão. Não afecta a fonte inglesa. Não é substituído quando o inglês é alterado. É assinalado como conteúdo exclusivo para que todos saibam que é intencional.

Quando a versão japonesa precisa de uma estrutura diferente, por exemplo, uma lista numerada em vez de pontos, porque é essa a convenção na escrita técnica japonesa, o tradutor pode alterar o tipo de bloco. O sistema regista isto como uma "adaptação de estrutura" e preserva-a em futuras actualizações.

Cada versão linguística torna-se um documento de primeira classe, não uma cópia sombra.

Como funciona, tecnicamente

Cada bloco no Rasepi tem:

Um UUID que persiste em todas as edições e traduções
Um hash de conteúdo** (SHA256) que muda quando o texto muda
Um índice de posição** para que os blocos fiquem na ordem correta
Um sinalizador de eliminação suave** para que a remoção de um bloco em inglês não quebre o alinhamento noutras línguas

Quando um bloco de tradução é criado, ele armazena o hash de conteúdo do bloco de origem. Em cada gravação, o sistema compara os hashes. Se coincidirem, a tradução é atual. Se não corresponderem, a tradução é marcada como obsoleta, e apenas esse bloco específico precisa de atenção.

Este é o mecanismo por detrás da redução de custos de 94%. A maioria das edições altera uma ou duas secções. O resto do documento, em todas as línguas, permanece inalterado.

Conteúdo único por língua

É aqui que as coisas se tornam genuinamente diferentes de qualquer outra plataforma.

No Rasepi, cada versão linguística pode conter:

Blocos traduzidos: traduções diretas da língua de origem, controladas quanto à sua obsolescência
Blocos únicos: conteúdo que só existe nessa língua, acrescentado pela equipa local
Blocos adaptados à estrutura: mesmo conteúdo de origem, formatação ou tipo de bloco diferente

Um único documento pode ter o seguinte aspeto em todas as línguas:

| Bloco | Inglês (fonte) | Alemão | Japonês | Português | Inglês (fonte) |-------|------------------|--------|----------| 1 | Introdução | Traduzido | Traduzido | Traduzido | | 2 | Passos de configuração | Traduzido | Estrutura adaptada (lista numerada) | | 3 | - | Conformidade DSGVO (única) | - | 4 | Implementação | Traduzido | Traduzido | | | 5 | - | - | Nota de ferramentas locais (única) | 6 | Resolução de problemas | Traduzido | Traduzido | Traduzido |

Cada equipa recebe exatamente a documentação de que necessita. Sem compromissos. Sem soluções alternativas. Sem limitações de tamanho único.

Controlo de atualidade entre idiomas

Cada versão linguística monitoriza a sua própria atualidade de forma independente. A fonte em inglês pode ter uma pontuação de 94 (revisto recentemente, todos os links válidos, grande número de leitores). A versão francesa pode ter uma pontuação de 71 (dois blocos obsoletos, um link quebrado específico para o conteúdo francês). A versão japonesa pode ter uma pontuação de 88 (todas as traduções são actuais, mas o número de leitores está a diminuir).

Este controlo da atualidade por língua significa:

Sabe exatamente quais as línguas que precisam de atenção
As traduções desatualizadas são descobertas automaticamente, não por acidente
As ferramentas de IA podem ter em conta a atualidade específica da língua ao fornecer respostas
Os painéis de controlo mostram a integridade dos conteúdos por língua e não apenas por documento

O caso de negócio

As empresas que operam em vários idiomas enfrentam uma realidade simples: a sua documentação é um ativo ou um passivo em todos os mercados que serve.

Quando a sua equipa de Berlim está a trabalhar a partir de uma tradução alemã com três meses de atraso em relação à fonte inglesa, está a tomar decisões com base em informações desactualizadas. Quando o seu escritório de Tóquio não pode adicionar contexto local a documentos partilhados porque o sistema de tradução o substitui, deixa de utilizar a wiki e cria a sua própria documentação sombra. Quando a sua equipa de São Paulo não tem documentos em português, a integração demora o dobro do tempo.

O custo não é apenas a taxa de tradução. É:

Integração mais lenta em mercados não ingleses
Esforço duplicado quando as equipas mantêm documentação paralela em ferramentas locais
Silos de conhecimento** que se formam quando o wiki oficial não serve a todos
Risco de conformidade quando os requisitos específicos da região não são capturados
Perda de confiança** no próprio sistema de documentação

A localização em bloco resolve tudo isto, não tornando a tradução mais barata (embora o faça), mas tornando cada versão linguística num documento vivo, mantido e fiável.

Começar

Se está a gerir uma equipa multilingue em qualquer plataforma de documentação hoje em dia, aqui está uma verificação rápida:

**Escolha o seu documento mais importante e verifique-o em todas as línguas. Cada versão está actualizada?
Pergunte às suas equipas que não falam inglês: confiam nos documentos traduzidos? Utilizam-nos?
**As equipas estão a manter wikis locais, páginas Notion ou mensagens fixas no Slack porque os documentos oficiais não lhes servem?
**Calcule os seus gastos com tradução. Quanto está a pagar por atualização, e quanto desse valor é para retraduzir conteúdo que não mudou?

Se as respostas forem incómodas, não é o único. A maioria das empresas não descobre a lacuna até que ela cause um problema real: uma questão de conformidade, uma implantação malfeita, um novo contratado que passou duas semanas seguindo instruções desatualizadas.

O conhecimento multilingue não é uma coisa boa de se ter. Para qualquer empresa que opere além-fronteiras, é a base da forma como as equipas se alinham, tomam decisões e enviam. A questão é se a sua plataforma de documentação o trata dessa forma.

Cada idioma merece ser um cidadão de primeira classe na sua base de conhecimento. Não uma cópia. Não uma sombra. Um documento real, mantido e confiável.

É isso que o Rasepi oferece. Tradução em nível de bloco, conteúdo exclusivo por idioma, rastreamento de atualização independente e uma redução de 94% nos custos de tradução. Tudo automático. Tudo desde o primeiro dia.

Veja a publicação multilingue em ação →

Atualização de conteúdo, parte 2: além das datas de validade

2026-03-18T00:00:00Z

*Esta é a Parte 2 da nossa série de atualização de conteúdos. A Parte 1 aborda a razão pela qual a atualidade é importante e o que significa realmente. Esta publicação continua de onde parou: porque é que as datas de validade não são suficientes e o que é a monitorização contínua.

Digamos que faz a coisa responsável. Cada documento na sua wiki tem uma data de revisão. Seis meses após a criação, talvez doze para material de referência estável. Quando a data chega, o proprietário recebe uma notificação: reveja isto ou será assinalado.

Isso é melhor do que a maioria das empresas faz. A maioria das empresas não faz nada. O documento fica lá, a deteriorar-se lentamente, e ninguém repara até que alguém siga as instruções e algo se estrague.

Mas aqui está a verdade incómoda: **Já vi documentos ficarem perigosamente obsoletos dias depois da sua última revisão, e uma data de revisão não o detecta.

O que é que as datas de validade realmente resolvem

As datas de validade resolvem o problema da responsabilidade. Elas respondem à pergunta: "Quem é responsável por confirmar que isto ainda está correto, e quando?"

Isso é verdadeiramente valioso. Sem isso, a documentação entra naquilo a que chamamos o vazio de propriedade, um estado em que todos assumem que alguém a está a manter, por isso ninguém o faz. Definir uma data de revisão atribui a uma única pessoa uma única obrigação numa data específica. Simples. Claro. Eficaz.

Eis como são as datas de expiração na prática:

Um documento é criado com uma data de revisão de 90 dias
14 dias antes da data de expiração, o proprietário é notificado
Na data de expiração, o documento é assinalado como "necessita de revisão"
O proprietário revê, confirma que ainda está correto e prolonga a data
Ou actualiza-o, ou reatribui-o, ou arquiva-o

Este é um sistema sólido. Detecta a deterioração lenta, o documento em que ninguém pensou durante um ano. Cria uma cadência regular de revisão. Torna a propriedade visível.

**Mas tem um ponto cego do tamanho de um continente.

O que as datas de expiração perdem

Entre datas de revisão, um documento vive numa caixa negra. Reviu-o a 15 de janeiro. A próxima revisão é a 15 de abril. No dia 3 de fevereiro, qualquer uma destas coisas pode acontecer:

Os links quebram silenciosamente

Um URL externo que você referenciou retorna um 404. Um link interno aponta para um documento que foi arquivado. Um repositório de código foi renomeado e todos os links do GitHub no seu documento estão agora mortos. O seu documento ainda está bem. A data de expiração é só daqui a dois meses. Ninguém sabe que os links estão quebrados.

Alterações de conteúdo relacionadas

Você escreveu um guia de implantação que faz referência ao seu documento de arquitetura. Em fevereiro, alguém reescreve completamente o documento de arquitetura. Novos padrões, nova infraestrutura, novas convenções. Seu guia de implantação ainda faz referência à arquitetura antiga. Ainda não está tecnicamente errado, mas está à deriva. Quando chegar a data da revisão, a lacuna pode ser significativa.

O número de leitores cai para zero

O seu documento costumava ser lido por 40 pessoas por mês. Depois, um processo mudou e já ninguém precisa dele, mas também ninguém o arquivou. Fica nos resultados de pesquisa, ocupando espaço, ocasionalmente confundindo um novo contratado que não sabe que é irrelevante. A data de expiração não se preocupa com os leitores. Vai enviar um ping para o proprietário na data prevista, independentemente disso.

As traduções ficam para trás

A fonte em inglês foi actualizada a 10 de fevereiro. As traduções em francês, alemão e japonês estão agora desatualizadas. Mas a data de expiração dessas versões traduzidas é apenas em maio. Durante três meses, as equipas não inglesas estão a ler conteúdos desactualizados e não o sabem.

Leitores sinalizam problemas

Um leitor deixa um comentário: "O passo 3 já não funciona, o sinalizador CLI foi descontinuado." Esse comentário fica lá. A data de expiração ainda está a semanas de distância. A próxima pessoa que ler o documento pode não ver o comentário. A pessoa seguinte não verá de certeza.

**A expiração é um ponto de controlo programado. Estes são eventos não programados. O intervalo entre os dois é onde a documentação obsoleta causa mais danos.

Atualidade: monitorização contínua

A pontuação de frescura preenche a lacuna que as datas de expiração deixam em aberto. Em vez de verificar a saúde de um documento uma vez a cada 90 dias, o Freshness monitoriza-o continuamente. Todos os dias, em segundo plano, sem que ninguém precise de fazer nada.

Eis como funciona no Rasepi:

Cada documento recebe uma pontuação de frescura em tempo real de 0 a 100, calculada a partir de vários sinais:

Sinal	O que detecta	Porque é importante
Saúde do link**	URLs quebrados, redireccionados ou inacessíveis	Os links quebrados corroem a confiança e desperdiçam tempo
Estado da revisão**	Se o documento foi revisto dentro do prazo	A verificação de base da responsabilidade
Tendências de leitura**	Se alguém está realmente a ler este documento	Um baixo número de leitores sugere que o documento pode ser irrelevante
Quando o documento foi modificado pela última vez em relação ao conteúdo relacionado	Detecta desvios em relação à base de conhecimento circundante
Alinhamento da tradução**	Se todas as versões linguísticas são actuais	Traduções obsoletas significam que as equipas de outros mercados trabalham com informação antiga
Se os leitores relataram problemas	Deteção de desatualização por crowdsourcing
Referências cruzadas**	Se os documentos a que este documento está ligado estão eles próprios desactualizados	A desatualização é contagiosa

Cada sinal contribui para a pontuação global. Um documento pode perder pontos de atualidade devido a um link quebrado hoje, mesmo que a sua data de revisão seja só daqui a semanas. É esse o objetivo.

Como os dois funcionam em conjunto

A expiração e a atualização não são abordagens concorrentes. São camadas complementares:

As datas de validade são a camada de governação. Criam uma cadência regular de revisão humana. Alguém tem de olhar para este documento num determinado horário e confirmar que ainda está correto. Isto permite verificar o que a automatização não consegue: se o conteúdo ainda está correto, se os conselhos ainda são sólidos, se o processo que descreve ainda reflecte a realidade.

A pontuação de atualidade é a camada de monitorização. Apanha tudo entre as datas de revisão: as ligações quebradas, os desvios de tradução, os documentos abandonados, a deterioração contextual que acontece quando o mundo se move e um documento não.

Juntos, eles criam um sistema onde:

Cada documento é revisto por um humano num horário regular (expiração)
Entre revisões, sinais automatizados detectam os problemas à medida que vão surgindo (atualidade)
Ambos os sistemas alimentam uma única pontuação de confiança que todos podem ver
Essa pontuação afecta a forma como o documento é classificado na pesquisa e se as ferramentas de IA o utilizam como fonte

O impacto da pontuação

É aqui que as coisas se tornam práticas. No Rasepi, a pontuação de frescura de um documento afecta diretamente a sua visibilidade:

Pontuação 80-100:** Visibilidade total. Aparece normalmente nos resultados da pesquisa. Elegível como fonte de respostas de IA. Sem sinalizações.
Pontuação 50-79:** Visibilidade reduzida. Aparece na pesquisa com um indicador de inatividade. As ferramentas de IA podem retirar-lhe a prioridade como fonte. O proprietário é notificado.
Pontuação inferior a 50:** Sinalizada. Deslocado para baixo nos resultados de pesquisa de forma significativa. Excluído totalmente das respostas de IA. O proprietário recebe uma notificação urgente.

Isto cria um ciclo de feedback. Quando a pontuação de um documento desce, o proprietário é pressionado a corrigi-lo, não porque chegou uma data arbitrária, mas porque algo mudou efetivamente. O link quebrado, a tradução obsoleta, o declínio de leitores, são sinais reais que exigem atenção agora, não em seis semanas.

Um exemplo prático

Vamos analisar um cenário:

março 1: O seu "Manual de resposta a incidentes" tem uma pontuação de 92. Foi revisto há duas semanas, todas as ligações são válidas, o número de leitores é elevado e as quatro versões linguísticas estão actualizadas.

**8 de março: Alguém reestruturou a página de status de engenharia. Três URLs no manual agora redireccionam. A pontuação de atualidade desce para 78. O proprietário recebe uma notificação: "3 links quebrados detectados."

março 10: O proprietário corrige os links. A pontuação recupera para 89.

março 15: A versão inglesa é actualizada com um novo caminho de escalonamento. As traduções francesa e alemã estão agora obsoletas (incompatibilidade de hash de conteúdo). A pontuação cai para 74.

março 17: As traduções são actualizadas. A pontuação volta a ser 91.

**20 de março: Os dados de leitura mostram que a versão japonesa não é acedida há 30 dias. A pontuação desce para 86. Um sinal subtil, mas registado.

**1 de abril: Chega a data prevista para a revisão. O proprietário revê o conteúdo, confirma que está correto e prolonga a expiração até 1 de julho. A pontuação mantém-se em 86 porque o sinal dos leitores ainda está presente.

Em nenhum momento a equipa esperou por uma data de revisão para detetar um problema. O sistema de atualidade assinalou os problemas em poucos dias. A data de revisão forneceu o ponto de controlo da governação. Ambas as camadas estão a fazer o seu trabalho.

Porque é que "definir uma data de revisão" já não é suficiente

Há cinco anos atrás, as datas de expiração poderiam ser suficientes. A documentação era lida por pessoas e estas podiam fazer juízos de valor. Se um documento parecesse um pouco estranho, as pessoas perguntavam por ele.

Atualmente, a documentação é uma infraestrutura. Alimenta as ferramentas de IA, a automatização da integração, os sistemas de conformidade e os motores de pesquisa que apresentam resultados sem contexto. Estes sistemas não fazem juízos de valor. Eles consomem o conteúdo como ele é e o redistribuem em escala.

Um documento com links quebrados e traduções obsoletas que ainda tem três semanas até a data de revisão pode causar muitos danos nessas três semanas, especialmente se um assistente de IA estiver fornecendo respostas com confiança com base nele.

**As datas de validade são a abordagem mínima viável para a governação da documentação. A pontuação de frescura é o que é necessário quando a documentação é consumida por sistemas que não conseguem pensar por si próprios.

Começar

Se já tem datas de validade nos seus documentos (ainda bem para si, a sério, a maioria das equipas nem sequer faz isso), eis como colocar a frescura em camadas:

**Comece a monitorizar as hiperligações. Faça uma verificação de hiperligações quebradas nos seus 50 documentos principais. O número irá provavelmente surpreender-te.
**Se tiver documentos multilingues, compare as datas de última edição entre a fonte e as traduções. Quantos estão mais de um mês atrasados?
**Veja o número de leitores. Quais os documentos que não recebem qualquer tráfego? Ainda são necessários ou devem ser arquivados?
**Fale com a sua equipa de IA. Se tiver um assistente de IA interno, pergunte-lhe quais os documentos que estão a ser obtidos. Depois, verifique a atualidade desses documentos.

É provável que descubra que os seus documentos tecnicamente não expirados têm muitos problemas que as datas de expiração nunca irão detetar.

As datas de validade dizem-lhe se alguém verificou um documento recentemente. A frescura diz-lhe se o documento está realmente saudável neste momento. Um é um evento de calendário. O outro é um sinal vivo.

Precisa de ambos. Mas se só tiver datas de validade, está a voar às cegas entre os pontos de controlo.

Um documento não se torna obsoleto na sua data de revisão. Torna-se obsoleto no momento em que algo muda e ninguém dá por isso. A pontuação de frescura é notada.

O Rasepi combina datas de expiração obrigatórias com monitorização contínua da atualidade. Cada documento ganha ou perde a sua pontuação de confiança, em tempo real. Sem esperas, sem pontos cegos, sem surpresas na altura da revisão.

Veja como funciona a pontuação de frescura →

Esta é a Parte 2 de uma série de duas partes. Se ainda não a leu, comece pela Parte 1: A métrica que a sua equipa não está a seguir.

Atualidade do conteúdo, Parte 1: A métrica que a sua equipa não está a monitorizar

2026-03-16T00:00:00Z

Há um momento que todas as equipas de engenharia já viveram. Alguém encontra um documento no wiki interno, segue as instruções e algo quebra. A pessoa envia uma mensagem para o canal: "Isto ainda está correto?" Ninguém sabe. A pessoa que o escreveu saiu há oito meses. O documento diz que foi editado pela última vez em 2024.

Este é o problema da atualidade. E está a piorar.

O contrato antigo está a acabar

Durante muito tempo, a documentação tinha um contrato implícito: alguém a escrevia, todos confiavam nela e, ocasionalmente, alguém a actualizava. Talvez. Esse contrato funcionava, por pouco que fosse, quando os documentos eram consumidos apenas por pessoas que podiam fazer juízos de valor. Se um guia de configuração parecesse um pouco estranho, um engenheiro sénior adaptava-se rapidamente.

Mas esse mundo acabou. Atualmente, a sua documentação não é lida apenas por humanos. É consumida por ferramentas de IA, chatbots internos, automação de integração e sistemas de pesquisa que tratam cada palavra como uma verdade equivalente. Um assistente de IA não olha para um documento e pensa "hmm, isto parece um pouco antiquado." Lê o texto, processa-o como um facto e serve-o com total confiança.

**Documentação desactualizada mais IA é igual a respostas erradas com confiança e em grande escala.

O que significa realmente a atualidade

Frescura não é apenas "quando foi editado pela última vez". Um documento pode ter sido editado ontem e ainda fazer referência a uma API obsoleta. A verdadeira atualidade é um sinal composto:

Estado da revisão. Alguém confirmou explicitamente que isto ainda está correto?
Os URLs dentro do documento ainda estão a ser resolvidos?
Leitores: alguém está realmente a usar isto, ou foi abandonado?
Os documentos relacionados mudaram enquanto este permaneceu o mesmo?
Alinhamento da tradução: se este documento existe em cinco línguas, todas elas estão actualizadas?
Sinais da comunidade: os leitores assinalaram-no como desatualizado?

Cada um destes indicadores diz-lhe algo diferente. Juntos, dão-lhe uma pontuação de confiança: um único número que representa a confiança que deve depositar num conteúdo neste momento.

Porque é que isto é importante agora, especificamente

Três factores convergiram para tornar a atualidade urgente:

1. A IA está a consumir a sua base de conhecimentos

Se você implantou um sistema RAG interno, usa o Copilot em seu IDE ou tem um assistente de IA respondendo a perguntas de seus documentos, a qualidade do material de origem determina diretamente a qualidade da saída. Nunca foi tão literal o termo "lixo dentro, lixo fora".

Quando um programador pergunta ao seu assistente de IA "como faço para implementar no staging?" e este responde utilizando um runbook com dois anos que faz referência a uma infraestrutura que já migrou, o custo não é apenas uma resposta errada. É a perda de confiança em todo o sistema.

2. As equipas estão mais distribuídas do que nunca

Uma equipa em Berlim, outra em São Paulo, uma terceira em Tóquio. Todos a ler a mesma documentação, muitas vezes em línguas diferentes. Quando a fonte em inglês fica obsoleta, todas as traduções construídas em cima dela também ficam obsoletas, mas ninguém nota porque as traduções são mantidas separadamente, se é que são mantidas.

3. A pressão da conformidade e da auditoria está a aumentar

Os setores regulamentados estão começando a perguntar: "Você pode provar que essa documentação estava atualizada no momento em que foi referenciada?" Se a sua resposta for "bem, provavelmente alguém a verificou", isso não vai aguentar.

Como é uma abordagem que dá prioridade à atualidade

A ideia central é simples: cada documento deve ganhar continuamente o direito de ser confiável.

Isto significa:

**Todos os documentos têm uma data de expiração quando são criados. Sem excepções. Quando a data chega, o proprietário é notificado e o documento é assinalado até que alguém o volte a aprovar explicitamente.
**Em segundo plano, o sistema verifica continuamente se há links quebrados, tendências de leitura e alterações contextuais. Estes sinais alimentam uma pontuação em tempo real que é actualizada sem que ninguém tenha de fazer nada.
A atualidade afecta a visibilidade. Este é o mecanismo principal. Um documento com uma pontuação elevada aparece no topo dos resultados de pesquisa e é elegível para ser utilizado como fonte de respostas de IA. Um documento com pontuação baixa desce na classificação. Se ficar abaixo de um limiar, é totalmente excluído das respostas da IA.
**Transparência: todos podem ver porque é que um documento obteve a pontuação que obteve. Links quebrados, revisão atrasada, baixo número de leitores, os sinais são visíveis, não estão escondidos num relatório de backend que ninguém lê.

O custo de não fazer nada

Eis o que acontece quando não se controla a atualidade:

Os novos contratados seguem documentos de integração desactualizados e passam a primeira semana confusos
As ferramentas de IA dão respostas erradas e ninguém percebe porquê
Os documentos de conformidade desatualizam-se silenciosamente e criam riscos de auditoria
As traduções ficam dessincronizadas e as equipas de diferentes regiões trabalham com versões diferentes da realidade
Os engenheiros deixam de confiar inteiramente no wiki e recorrem às mensagens do Slack, o que cria o seu próprio silo de conhecimento

O custo composto da documentação obsoleta é enorme, mas é invisível até que algo se estrague.

Um ponto de partida prático

Não precisa de rever tudo de uma vez. Comece com isto:

Audite os seus 20 documentos mais lidos Quando foram revistos pela última vez? As hiperligações ainda são válidas? O conteúdo ainda é exato?
Defina datas de revisão. Mesmo que não faça mais nada, colocar uma data de "revisão por" em cada documento cria responsabilidade.
**Se tiver um assistente de IA interno, veja quais os documentos que ele está a obter. Esses documentos são actuais?
**Torne a atualidade visível. Coloque a pontuação onde as pessoas a possam ver, junto ao título do documento, nos resultados da pesquisa, na barra lateral. A visibilidade cria pressão para a manter.

A atualidade da documentação não é uma caraterística. É uma mudança fundamental na forma como pensamos sobre o conhecimento organizacional. Num mundo em que as ferramentas de IA consomem e redistribuem os seus documentos em escala, a questão não é se pode dar-se ao luxo de se preocupar com a atualidade. É se pode dar-se ao luxo de não o fazer.

Cada documento deveria ter de provar que ainda vale a pena confiar nele. Não uma vez. Continuamente.

É isso que estamos a construir na Rasepi. Uma plataforma onde a atualidade não é uma reflexão tardia. É a base sobre a qual tudo o resto é construído. Aplicação de revisões, pontuação de saúde em tempo real, pesquisa ponderada por frescura e respostas de IA que apenas utilizam fontes em que pode confiar.

Veja como funciona →

Esta é a Parte 1 de uma série de duas partes. Em Parte 2: Para além das datas de validade, exploramos a forma como a monitorização contínua da frescura preenche as lacunas que as datas de revisão deixam em aberto.

Ensine a sua IA a ignorar documentação obsoleta

2026-03-12T00:00:00Z

Eis o que acontece quando implementa um assistente de IA no topo da sua base de conhecimentos interna:

Um novo engenheiro pergunta: "Como é que configuro o ambiente de teste?"

A IA pesquisa a sua documentação, encontra três documentos relevantes, sintetiza uma resposta e apresenta-a com confiança. O engenheiro segue as instruções. Os dois primeiros passos funcionam. O terceiro passo faz referência a uma ferramenta CLI que foi descontinuada há seis meses. O quarto passo descreve uma configuração de infraestrutura que foi substituída durante uma migração que ninguém documentou.

O engenheiro está preso. Envia uma mensagem para o canal da equipa. Alguém diz: "Oh, esse documento é muito antigo". A IA não sabia disso. Não pode saber. Apenas foi buscar tudo o que encontrou e apresentou-o como verdade.

**Este é o comportamento por defeito de todos os sistemas RAG, de todas as ferramentas de pesquisa de IA e de todos os assistentes com LLM que já utilizou em documentos internos. Eles vão buscar tudo. Não fazem discriminações. Não conseguem distinguir o que é recente do que é obsoleto.

E isso está a destruir a confiança nas ferramentas de IA mais rapidamente do que essas ferramentas a conseguem construir.

Porque é que os assistentes de IA são cegos à qualidade

Os grandes modelos de linguagem e os sistemas de geração aumentada de recuperação (RAG) funcionam encontrando texto que é semanticamente relevante para uma consulta e, em seguida, utilizando esse texto para gerar uma resposta. A correspondência de relevância é normalmente excelente. A pesquisa vetorial e os embeddings são genuinamente bons a encontrar conteúdos relacionados com uma pergunta.

Mas relevância não é o mesmo que fiabilidade.

Um documento escrito em 2023 sobre o seu processo de implantação do Kubernetes é altamente relevante para a pergunta "como faço para implantar na produção?" Também é completamente errado se você migrou para uma plataforma diferente em 2024. A IA vê texto relevante. Ela não vê um documento que está 18 meses desatualizado, com links quebrados e zero leitores.

A maioria dos sistemas de IA tem exatamente um sinal de classificação: semelhança semântica com a consulta. É só isso. Eles não verificam:

Quando é que este documento foi revisto pela última vez?
As hiperligações nele contidas ainda são válidas?
Alguém está realmente a ler este documento?
O conteúdo foi assinalado pelos leitores como desatualizado?
Trata-se de um rascunho, de uma página arquivada ou de um documento atual?
Se este documento existir em várias línguas, as traduções estão actualizadas?

Sem estes sinais, a IA está a fazer a correspondência de palavras-chave com passos adicionais. Uma correspondência de palavras-chave impressionante, sim, mas fundamentalmente incapaz de lhe dizer se a resposta que está a dar se baseia em conteúdos em que pode confiar.

O problema da confiança

Isto não seria tão perigoso se as ferramentas de IA apresentassem respostas incertas com as devidas advertências. Mas não o fazem. Não é assim que os LLMs funcionam. Geram textos fluentes e confiantes, independentemente de o material de origem ser atual ou antigo.

Um ser humano que leia um artigo wiki pode reparar que parece datado. O layout da página é antigo. As capturas de ecrã mostram uma interface que já não existe. Há um comentário no final a dizer "isto está desatualizado". Um ser humano pode fazer juízos de valor.

Uma IA não pode. Lê o texto, processa-o como se fosse equivalente a qualquer outro texto e gera uma resposta que soa a autoridade. O utilizador, especialmente um novo contratado que não sabe como é o processo atual, não tem motivos para duvidar.

**Quanto mais confiante a IA parecer, mais danos causa o material de origem obsoleto.

O que a IA realmente precisa

Para que um assistente de IA possa dar respostas fiáveis a partir da sua base de conhecimentos, precisa de mais do que texto e inserções. Precisa de metadados que lhe digam quais os documentos que vale a pena utilizar como fontes. Especificamente:

1. Pontuação de frescura

Um sinal numérico que representa o quão saudável um documento está neste momento. Não quando foi editado pela última vez, isso é apenas uma entrada. Uma verdadeira pontuação de frescura combina o estado da revisão, a saúde da ligação, o número de leitores, o alinhamento da tradução e a deriva contextual num único número.

Quando um documento tem uma pontuação acima de um limite (digamos, 70 em 100), é elegível para ser utilizado como fonte de respostas de IA. Abaixo desse limiar, é excluído. Sem excepções.

Este mecanismo único elimina a classe mais perigosa de erros de IA: respostas erradas com confiança baseadas em fontes obsoletas.

2. Status de expiração

Este documento está atualmente dentro da sua janela de revisão, ou expirou sem nova aprovação? Um documento expirado deve ser fortemente despriorizado ou totalmente excluído, independentemente da relevância que o seu conteúdo possa ter para a consulta.

No Rasepi, os documentos expirados são assinalados e as suas pontuações de atualidade baixam automaticamente. Um sistema de IA que consulte a base de conhecimentos pode ver este estado e agir em conformidade.

3. Etiquetas de classificação

Nem todos os documentos têm o mesmo objetivo. Um rascunho não deve ser usado como fonte. Um documento arquivado não deve aparecer nas respostas de IA. Um documento apenas interno não deve aparecer em consultas de ferramentas externas.

As etiquetas de classificação dão à IA um contexto sobre o tipo de documento que está a analisar:

Publicado Atual, aprovado, seguro para utilização
Rascunho: trabalho em curso, não deve ser citado
Em revisão.** Expiração acionada, a aguardar reaprovação
Arquivado.** Já não está ativo, mantido apenas para referência
Interno / Externo Controla o âmbito da visibilidade

Quando um assistente de IA processa uma consulta, pode filtrar por classificação antes mesmo de analisar a relevância do conteúdo. Um projeto de documento que corresponda perfeitamente à consulta nunca deve ser apresentado como resposta.

4. Sinais ao nível da língua

Se a sua base de conhecimentos for multilingue, a IA precisa de saber se a versão de onde está a ser retirada é atual. Uma tradução francesa com três meses de atraso em relação à fonte inglesa é tecnicamente relevante em francês, mas a informação pode estar desactualizada.

O Rasepi monitoriza a atualidade ao nível da língua. Cada tradução tem a sua própria pontuação com base na alteração dos blocos de origem desde a última atualização da tradução. Uma IA que consulte a base de conhecimentos em francês pode ver que a versão francesa de um documento está desactualizada e..:

Recuar para a fonte inglesa (que é atual)
Incluir uma advertência de que a versão francesa pode estar desactualizada
Excluir totalmente o documento

5. Sinais do leitor

Se vários leitores tiverem assinalado um documento como desatualizado, esse sinal deve reduzir o peso do documento nas respostas da IA. Os sinais de qualidade de crowdsourcing são ruidosos, mas são valiosos, especialmente quando combinados com outras métricas de atualidade.

Como isto funciona na prática

Vamos ver o que acontece quando um assistente de IA consulta uma base de conhecimento Rasepi:

Query: "Qual é o nosso processo para lidar com um incidente P1 às 2 da manhã?"

**Passo 1: Recuperação com filtragem: O sistema procura documentos semanticamente relevantes. Antes de classificar, filtra:

Documentos com pontuação de frescura inferior ao limiar
Documentos expirados que não tenham sido reaprovados
Rascunhos e conteúdos arquivados
Documentos cuja versão linguística é obsoleta (se a consulta estiver numa língua não primária)

**Entre os restantes documentos, aqueles com pontuações de frescura mais elevadas têm uma classificação mais elevada. Um documento com uma pontuação de 94 ultrapassa um com uma pontuação de 72, mesmo que o documento com pontuação de 72 tenha uma semelhança semântica ligeiramente superior.

**A IA gera uma resposta a partir das fontes filtradas e classificadas como frescas. Cada fonte é citada com a sua pontuação de frescura visível.

**Se a melhor fonte disponível tiver uma pontuação de frescura limítrofe, a IA inclui uma advertência: "Nota: A fonte principal desta resposta foi revista pela última vez há 60 dias. Pode querer verificar com a equipa."

Compare isto com o comportamento predefinido: encontrar texto relevante, gerar uma resposta confiante, esperar pelo melhor.

O que acontece quando não se faz isto

As consequências dos sistemas de IA que funcionam com bases de conhecimento não filtradas são previsíveis e dispendiosas:

**A utilização mais comum da IA para documentos internos é a integração. Os novos contratados, por definição, não sabem o que é atual e o que é obsoleto. Eles confiam na IA. A IA confia em tudo. Os documentos obsoletos são apresentados com confiança.

**Se o seu assistente de IA fornecer orientações sobre processos regulamentares utilizando documentos desactualizados, o conselho pode não só estar errado, como também não estar em conformidade. "A IA disse-me para o fazer" não se sustenta numa auditoria.

**Cada vez que a IA dá uma resposta errada, os utilizadores confiam um pouco menos nela. Após três ou quatro más experiências, deixam de a utilizar. O investimento em ferramentas de IA não tem qualquer valor porque o conteúdo subjacente não era fiável.

**Quando as pessoas perdem a confiança na base de conhecimentos oficial (e na IA construída em cima dela), criam a sua própria base de conhecimentos: Mensagens do Slack, notas pessoais, conhecimento tribal partilhado em reuniões. A fragmentação que o wiki deveria evitar acontece na mesma, mas de forma diferente.

A correção está na fonte, não no modelo

Existe a tentação de resolver este problema na camada de IA: melhores avisos, pipelines RAG mais sofisticados, modelos ajustados que podem, de alguma forma, detetar a obsolescência apenas a partir do texto. Esta é a abordagem errada.

A solução está na fonte. Se os seus documentos contêm metadados ricos e precisos sobre o seu estado atual (pontuação de frescura, estado de expiração, classificação, alinhamento linguístico, sinais do leitor), então qualquer sistema de IA pode utilizar esses metadados para tomar melhores decisões. Não precisa de um modelo mais inteligente. Precisa de documentos mais inteligentes.

É isso que o Rasepi proporciona:

Cada documento tem uma pontuação de frescura** que é actualizada continuamente com base na saúde da ligação, nos leitores, no estado da revisão e muito mais
Cada documento tem uma data de expiração** que acciona a revisão quando chega
Cada documento tem uma classificação** (publicado, rascunho, em revisão, arquivado)
Cada versão linguística tem o seu próprio sinal de atualização** para que as traduções obsoletas sejam detectadas de forma independente
As bandeiras de leitor e o rastreio de referências cruzadas** acrescentam sinais de qualidade adicionais

Quando um sistema de IA consulta a base de conhecimentos do Rasepi, todos estes metadados estão disponíveis. A IA não tem de adivinhar se um documento é de confiança. O documento diz-lhe.

Um ponto de partida prático

Se tiver um assistente de IA a funcionar atualmente na sua base de conhecimentos, pode começar a avaliar o problema em 30 minutos:

Faça ao seu assistente de IA 10 perguntas para as quais sabe as respostas. Observe quais as respostas que utilizam fontes desactualizadas. É provável que encontre pelo menos 2-3 em cada 10 baseadas em conteúdos desactualizados.
Verifique os documentos de origem. Para cada resposta dada pela IA, consulte o documento de origem. Quando é que foi revisto pela última vez? As ligações são válidas? Confiarias nele se fosses tu a lê-lo?
**Encontre o seu documento mais antigo e negligenciado que ainda aparece nos resultados de pesquisa. Faça à IA uma pergunta que o faça aparecer. A IA usa-o? É quase certo que sim.
**Quantas consultas por dia é que o seu assistente de IA trata? Se 20-30% das respostas se basearem em conteúdos obsoletos, qual é o custo em termos de perda de tempo, decisões erradas e perda de confiança?

Os assistentes de IA são tão bons quanto o conteúdo em que se baseiam. Atualmente, a maioria deles trata todos os documentos da sua base de conhecimentos como igualmente válidos. Vão buscar tudo, o documento que foi revisto ontem e aquele em que ninguém tocou durante dois anos, e apresentam-no com a mesma confiança.

Isso não é um problema de modelo. É um problema de qualidade dos dados. E a solução é simples: dar aos seus documentos metadados que digam às ferramentas de IA em que confiar.

O seu assistente de IA não deve parecer confiante relativamente a uma resposta obtida a partir de um documento que ninguém reviu em 18 meses. Com os sinais corretos, não o fará.

O Rasepi faz com que cada documento tenha a sua própria pontuação de confiança: atualidade, estado de expiração, classificação, alinhamento linguístico. As ferramentas de IA consultam a base de conhecimentos e obtêm não só o conteúdo, mas também o contexto. As fontes fiáveis vêm à superfície. As obsoletas não aparecem. É assim que a documentação baseada em IA deve funcionar.

Ver como o Rasepi funciona com ferramentas de IA →

Falar com os documentos é melhor do que lê-los

2026-03-10T00:00:00Z

Há uma razão para as pessoas dizerem "vamos falar sobre isso" quando algo é complexo.

Quando estamos a tentar compreender uma nova ideia, resolver um problema ou recordar um processo sob pressão, a conversa é muitas vezes mais fácil do que a leitura. Não porque a leitura seja má. A leitura é uma das ferramentas mais poderosas que o ser humano já desenvolveu. Mas a leitura é uma competência aprendida que se sobrepõe a algo muito mais antigo: a fala.

Somos faladores muito antes de sermos leitores.

Isso é mais importante do que as pessoas imaginam, especialmente agora que a maior parte do conhecimento do mundo vive em documentos, wikis, PDFs e longas páginas internas que ninguém quer abrir a menos que seja absolutamente necessário.

A leitura é aprendida. A conversação é nativa.

Os seres humanos falaram durante muito tempo antes de escreverem qualquer coisa. As crianças aprendem a compreender a linguagem falada naturalmente. A leitura requer instrução explícita, repetição e anos de prática.

Mesmo para adultos altamente alfabetizados, a leitura continua a ser um ato mais deliberado do que ouvir ou falar. Exige concentração visual, atenção contínua, memória de trabalho e interpretação da estrutura na página. Está a descodificar símbolos, a analisar frases, a construir contextos e a decidir o que é importante.

A conversação funciona de forma diferente. Quando a informação é transmitida de forma falada e interactiva, o cérebro tem uma experiência diferente:

Parece sequencial em vez de visualmente avassaladora
Dá feedback e esclarecimentos imediatos
Reduz a necessidade de analisar e filtrar grandes blocos de texto
reflecte a forma como as pessoas já pedem ajuda na vida real

Este último ponto é muito importante. Em situações de incerteza, a maioria das pessoas não quer instintivamente ler 1500 palavras. Querem perguntar: "O que é que faço a seguir?"

Falar reduz o atrito cognitivo

Um documento é estático. Contém tudo ao mesmo tempo.

Isso parece útil, e muitas vezes é. Mas também cria fricção. Uma página cheia de títulos, chamadas de atenção, ligações, notas, exemplos e casos extremos obriga o leitor a decidir o que deve ignorar. Isso é cognitivamente dispendioso.

Quando se fala com um sistema de informação, normalmente obtém-se a experiência oposta: relevância em primeiro lugar, detalhe em segundo.

Faz-se uma pergunta. Obtém uma resposta. Depois, faz uma nova pergunta.

Este padrão de interação reduz a sobrecarga mental de algumas formas importantes:

1. Reduz o espaço do problema

Um documento completo apresenta todo o cenário. Uma conversa apresenta o próximo passo útil.

Quando alguém pergunta, "Como é que eu integro um novo engenheiro?" normalmente não quer o manual completo imediatamente. Quer orientação. A conversa permite-lhes começar com pouco e expandir apenas quando necessário.

2. Preserva a memória de trabalho

A leitura exige que mantenha várias coisas na sua cabeça enquanto procura a parte relevante. A interação falada ou conversacional externaliza esse esforço. O sistema faz a maior parte da filtragem por si.

3. Parece socialmente familiar

Os seres humanos estão profundamente adaptados à troca de informações. Nós perguntamos. Alguém responde. Nós aperfeiçoamos. Eles esclarecem-nos. Este ciclo é uma das formas mais antigas de aprendizagem que temos.

Mesmo quando o "alguém" é um sistema, a estrutura continua a parecer natural.

A leitura não é passiva. É exatamente esse o objetivo.

Uma das razões pelas quais falar pode parecer mais fácil é o facto de a leitura não ser tão fácil como as pessoas supõem. Os leitores experientes fazem com que pareça fácil, mas o processo é altamente ativo.

Para ler bem, é preciso:

identificar a estrutura
inferir a importância
resolver ambiguidades
guardar o contexto na memória
ligar uma secção a outra
decidir quando passar os olhos e quando abrandar

Este é o verdadeiro trabalho cognitivo.

Em muitas situações, esse trabalho vale a pena. A leitura aprofundada ajuda a obter nuances, precisão e uma compreensão mais alargada. Mas noutras situações, especialmente quando alguém está cansado, stressado, sobrecarregado ou apenas a tentar desbloquear, falar é muitas vezes a opção mentalmente mais leve.

Isto é especialmente verdade no local de trabalho, onde as pessoas não estão normalmente a abordar a documentação em condições ideais. Estão:

a meio da tarefa
interrompidas
a mudar de contexto
estão a tentar resolver algo rapidamente
muitas vezes já ligeiramente frustrado

Nesse estado, o acesso conversacional à informação pode parecer dramaticamente melhor do que o acesso à primeira página.

Falar muda a relação com a informação

Há também uma dimensão emocional aqui.

Os documentos podem parecer formais e distantes. Eles implicam: leia tudo isto, compreenda-o corretamente e não perca nada de importante. Isto pode ser útil como material de referência, mas também pode criar hesitação.

A conversa parece permissiva. Pode ser-se vago. Pode perguntar mal. Pode admitir-se a confusão. Pode dizer: "Não sei bem o que procuro, mas preciso da informação sobre os pedidos de acesso."

Isso é importante porque as pessoas muitas vezes evitam a documentação não porque não gostem da informação, mas porque não gostam do esforço e da incerteza envolvidos na procura da parte correta da mesma.

Falar reduz essa barreira.

Porque é que isto é importante agora

Durante muito tempo, os documentos tinham de ser lidos porque não havia alternativa prática. A pesquisa ajudou as pessoas a encontrar páginas, mas não alterou o modelo de interação. Continuava a ser necessário abrir a página, digitalizá-la e extrair o que era necessário.

Isso está a mudar.

À medida que as interfaces se tornam mais conversacionais, as pessoas esperam cada vez mais que a informação responda em vez de simplesmente existir. Querem pedir o que precisam numa linguagem simples e receber algo adaptado ao momento.

Isto não torna a leitura obsoleta. Altera o seu papel.

A leitura torna-se a camada profunda. A conversação passa a ser a camada de acesso.

Os melhores sistemas suportam ambos:

falar quando se precisa de orientação ou rapidez
ler quando se precisa de profundidade, verificação ou contexto completo

O risco de simplificação excessiva

Há uma ressalva importante: falar com a informação só é melhor se as respostas forem fiáveis.

Se uma interface de conversação der respostas parciais, enganadoras ou demasiado confiantes, a experiência torna-se pior do que a leitura, porque retira ao utilizador a capacidade de inspecionar diretamente o material de origem.

Portanto, o futuro não é "substituir todos os documentos por voz". O futuro é dar às pessoas uma forma mais humana de aceder a documentos sem perder a profundidade e a precisão que o conhecimento escrito proporciona.

Esse equilíbrio é importante. A conversação é mais fácil, mas os documentos continuam a ter a estrutura duradoura, o detalhe e a responsabilidade de que as organizações necessitam.

Uma interface mais humana para o conhecimento

O ponto mais profundo é simples: as pessoas não pensam naturalmente em páginas. Pensam em perguntas, histórias, fragmentos e diálogos.

Nós perguntamos:

O que é que isto significa?
O que é que eu faço primeiro?
Qual é a parte importante?
Consegues explicar isso de outra forma?
O que é que mudou?

Estes são movimentos de conversação, não de leitura.

Por isso, quando falar com a informação parece mentalmente mais fácil do que lê-la, isso não é um sinal de preguiça intelectual. É normalmente um sinal de que a interface corresponde à forma como o cérebro prefere abordar a incerteza.

A leitura continua a ser essencial. Mas, como ponto de entrada para o conhecimento, a conversa é muitas vezes melhor porque está mais próxima daquilo que somos por natureza.

Não somos leitores em primeiro lugar. Somos primeiro faladores. Os sistemas de conhecimento mais intuitivos lembrar-se-ão disso.

Plataformas de documentação criadas para outra era

2026-03-08T00:00:00Z

O Confluence e o Notion não são produtos ruins. Isso precisa ser dito claramente no início.

Eles tiveram sucesso por boas razões. O Confluence tornou-se o local predefinido para a documentação interna em muitas empresas porque proporcionou às equipas um local central para escrever, organizar e partilhar conhecimentos. O Notion conquistou as pessoas com flexibilidade, experiências de escrita mais limpas e uma superfície de produto mais moderna.

Ambas as plataformas resolveram problemas reais na era para a qual foram criadas.

O problema agora é que o mundo à sua volta mudou mais depressa do que as suas fundações.

Já não estamos num mundo em que a documentação só precisa de ser escrita, armazenada e pesquisada. Estamos num mundo em que se espera cada vez mais que a documentação o seja:

legível por máquinas
consciente da atualidade
segura para recuperação por IA
suficientemente estruturada para a automatização
dinâmicas entre línguas e públicos
continuamente fiável, não apenas disponível

Esta é uma barreira diferente.

Foram criados para um modelo de conhecimento anterior à IA

As plataformas de documentação tradicionais foram concebidas com base num pressuposto simples: se a página existir e for pesquisável, o problema está praticamente resolvido.

Isto era suficientemente bom quando o utilizador principal era um ser humano que abria uma wiki, passava os olhos pela página e fazia a sua avaliação. Nesse modelo, a função da plataforma era facilitar a criação e a navegação.

A IA altera a descrição do trabalho.

Agora, a plataforma não está apenas a armazenar conhecimentos para as pessoas. Está a produzir material de origem para sistemas que recuperam, classificam, resumem e respondem a perguntas automaticamente.

Isto introduz novos requisitos a que as arquitecturas mais antigas não davam prioridade:

Que conteúdos são fiáveis neste momento?
Que páginas estão desactualizadas mas ainda são pesquisáveis?
Que secções foram alteradas recentemente?
Que versão linguística é a atual?
Que conteúdos são projectos, arquivados, específicos de uma região ou de baixa confiança?
Que documentos devem ser totalmente excluídos das respostas de IA?

Uma plataforma que não tenha sido construída em torno destas questões tem de as adaptar. Isso é sempre mais difícil do que concebê-las desde o início.

A força do legado transforma-se em travão do legado

Os produtos estabelecidos têm vantagens: distribuição, ecossistema, marca, familiaridade com o cliente, integrações e equipas que sabem como fazer o envio. Mas esses mesmos pontos fortes podem atrasar a mudança estrutural.

Porquê? Porque as plataformas maduras implicam compromissos.

Elas têm:

anos de decisões acumuladas sobre produtos
enormes bases instaladas com fluxos de trabalho existentes
expectativas em relação à compatibilidade com versões anteriores
plugins e extensões que dependem de comportamentos antigos
modelos de dados optimizados para os casos de utilização de ontem

Quando uma plataforma como o Confluence ou o Notion pretende acrescentar uma capacidade genuinamente nova, muitas vezes tem de a adaptar ao sistema existente e não através dele.

Este é o desafio da incumbência: não está apenas a construir o futuro, está a arrastar o passado consigo.

Acrescentar funcionalidades de IA não é o mesmo que tornar-se nativo da IA

Muitas plataformas estabelecidas estão agora a colocar a IA no topo. Resumos. Assistência à escrita. Melhorias na pesquisa. Interfaces de perguntas e respostas. O Confluence tem Atlassian Intelligence, o Notion tem Notion AI, e o GitBook adicionou AI-powered search. Estas funcionalidades são úteis. Algumas delas são boas.

Mas há uma diferença significativa entre:

adicionar caraterísticas de IA a um produto de documentação
construir um produto de documentação cuja arquitetura central pressupõe o consumo de IA desde o primeiro dia

A primeira abordagem conduz frequentemente a funcionalidades de assistência nas extremidades. A segunda altera a base.

Uma plataforma de conhecimento nativa de IA coloca questões de design diferentes desde o início:

como é que os documentos devem ser estruturados para que os sistemas possam raciocinar sobre eles com segurança?
como deve ser representada a confiança?
que metadados devem ser de primeira classe e não opcionais?
Como é que os conteúdos obsoletos devem perder visibilidade?
como é que as respostas devem ser restringidas quando as fontes subjacentes são fracas?

Estas são questões de arquitetura, não de caraterísticas.

As plataformas novas têm uma vantagem temporária

É aqui que as plataformas mais recentes podem ganhar, pelo menos durante algum tempo.

Uma nova plataforma tem a liberdade de conceber em função das restrições actuais e não dos hábitos de ontem. Não tem de preservar uma década de pressupostos sobre o que é um documento ou como uma wiki se deve comportar. Pode fazer escolhas diferentes numa fase inicial:

tratar a atualidade como um conceito de primeira classe
tornar a confiança na fonte visível tanto para humanos como para máquinas
armazenar metadados mais ricos sobre o estado do conteúdo
incorporar fluxos de trabalho multilingues no modelo principal, em vez de os acrescentar
decidir que a pesquisa e a recuperação por IA devem ser classificadas por confiança e não apenas por relevância

Essa liberdade é importante.

Na tecnologia, os operadores históricos são frequentemente mais fortes durante períodos estáveis. Os novos operadores são muitas vezes mais fortes quando o próprio modelo está a mudar.

A era da IA é uma dessas mudanças.

Porque é que isto é especialmente difícil para o Confluence

O Confluence é poderoso, mas vem de uma visão de mundo mais antiga. Foi construído em torno de [espaços de equipa, páginas, navegação hierárquica] (https://support.atlassian.com/confluence-cloud/docs/use-spaces-to-organize-your-work/) e de um [modelo empresarial rico em plug-ins] (https://marketplace.atlassian.com/). Essas escolhas faziam sentido. Ainda fazem sentido para muitas organizações.

Mas também significam que o produto está a carregar uma grande complexidade. As plataformas empresariais raramente se conseguem reinventar de forma limpa. Têm de negociar com a sua própria história.

Isso torna a modernização mais lenta. Não é impossível. Apenas mais lenta.

Quando os requisitos da era da IA exigem metadados mais limpos, uma modelação de confiança mais explícita ou uma governação de conteúdos mais opinativa, um sistema criado para uma flexibilidade máxima através de anos de extensões pode ter dificuldade em avançar de forma coesa.

Por que isso é especialmente complicado para o Notion

O Notion tem um problema diferente. Ele parece mais novo, mais leve e mais flexível. Mas a flexibilidade também pode funcionar contra ele.

O ponto forte do Notion é que [quase tudo pode se tornar uma página, um banco de dados, uma nota, um documento leve ou um espaço colaborativo] (https://www.notion.com/product). Essa flexibilidade é óptima para as equipas. Não é tão boa quando são necessárias garantias sólidas sobre o significado do conteúdo, o estado em que se encontra e se deve ser utilizado como uma fonte fiável por um sistema de IA.

Quanto mais livre for uma plataforma, mais difícil será impor posteriormente uma semântica fiável.

Os sistemas de IA prosperam com estrutura, metadados explícitos e sinais de confiança. Os espaços de trabalho flexíveis de uso geral precisam frequentemente de muita interpretação antes de o seu conteúdo ser seguro para esse tipo de utilização.

Nada disto significa que estão condenados

Seria uma análise preguiçosa dizer que o Confluence e o Notion não se podem adaptar. Claro que podem.

Têm equipas inteligentes, recursos significativos e fortes incentivos. Vão lançar mais capacidades de IA. Vão melhorar a recuperação, a assistência à criação, os resumos, a governação e os fluxos de trabalho estruturados. Com o tempo, poderão colmatar uma grande parte da lacuna.

Mas o tempo é importante.

Quando uma mudança como esta acontece, a vantagem pertence frequentemente a quem estiver disposto a reconstruir os pressupostos mais rapidamente. As plataformas mais recentes podem avançar com mais coerência porque não estão a adaptar-se tanto. Isso dá-lhes uma janela.

Pode não ser uma janela permanente. Mas é real.

A próxima fase das plataformas de documentação

A próxima geração de ferramentas de documentação será provavelmente julgada menos pela forma como permitem que as pessoas escrevam páginas e mais pela forma como gerem o conhecimento como um sistema de confiança.

Isso significa que os vencedores provavelmente farão cinco coisas bem:

Modelarão a confiança de forma explícita.
Distinguem o conhecimento atual do conhecimento obsoleto.
Tratarão a recuperação de IA como uma superfície central do produto e não como um complemento.
Suportarão conhecimentos multilingues e específicos do público sem fragmentação.
Darão às equipas um maior controlo sobre as informações que são apresentadas, a quem e em que condições.

Esta é uma categoria diferente da wiki clássica.

Porque é que os novos começos são importantes

Há momentos no software em que um produto novo tem uma vantagem, não porque os operadores históricos sejam incompetentes, mas porque a história é cara.

Este é um desses momentos.

Uma nova plataforma pode decidir, desde o primeiro dia, que os documentos não são apenas páginas. São fontes activas para humanos, agentes, sistemas de pesquisa e assistentes de IA. Esse pressuposto altera tudo a jusante.

O Confluence e o Notion podem lá chegar. Mas o caminho é mais longo porque têm de transformar sistemas que foram optimizados para outra era.

Essa transformação leva tempo. Entretanto, as plataformas mais recentes têm espaço para definir o que deve ser uma infraestrutura de conhecimento moderna.

A maior vantagem de uma nova plataforma não é a novidade. É a libertação de velhos pressupostos exatamente no momento em que esses pressupostos deixam de funcionar.

Este é um artigo de perspetiva. As afirmações sobre produtos concorrentes baseiam-se em documentação e anúncios de produtos disponíveis publicamente em março de 2026. Temos um respeito genuíno pelo Confluence e pelo Notion - são produtos excelentes que servem bem milhões de equipas.

Por dentro da arquitetura Rasepi: Plugins, Action Guards e Pipelines

2026-03-06T00:00:00Z

A maioria das plataformas de documentação fala sobre "extensibilidade" da mesma forma que as companhias aéreas falam sobre "espaço para as pernas". Tecnicamente presente, praticamente dececionante. Eu queria que a arquitetura do Rasepi fosse genuinamente extensível sem se tornar imprevisível, por isso construímos três sistemas interligados: plugins para capacidade, action guards para controlo, e pipelines para execução determinística.

Este post mostra como cada um deles funciona em nossa base de código atual.

O sistema de plugins: modular por design

Cada plugin no Rasepi implementa IPluginModule, uma única interface que declara o que o plugin é, quais serviços ele precisa, e quais rotas ele expõe:

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

O PluginManifest é puro dado. Ele descreve o plugin sem executar 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; }
}

Repare no UiContributions. Esse dicionário mapeia os pontos de extensão do frontend para os nomes dos componentes, então o frontend do Vue sabe quais componentes de UI cada plugin contribui (um botão da barra de ferramentas, um painel da barra lateral, uma página de configurações).

O registo é uma linha por cada plugin

Na inicialização, nós registramos plugins através de uma API fluente:

var pluginRegistry = new PluginRegistry();

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

Cada chamada instancia o módulo, armazena-o no registo e chama RegisterServices() para ligar as suas dependências. Depois que o aplicativo é construído, uma única linha mapeia todas as rotas de plugins:

app.MapPluginRoutes(pluginRegistry);

Por baixo do capô, cada plugin recebe um grupo de rotas com escopo em /api/plugins/{pluginId}/ com autorização aplicada automaticamente.

Exemplo real: o plugin Workflow

Aqui está o aspeto de um plugin real, o 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);
    }
}

A plataforma principal nunca faz referência a WorkflowService ou WorkflowPublishGuard diretamente. Descobre-os através do contentor DI. Essa é a chave para o acoplamento zero. A aplicação principal nunca toca no código do plugin.

Guardas de ação: a camada de controlo

Plugins adicionam capacidades. Os guardas de ação decidem se essa capacidade, ou qualquer ação do núcleo, tem permissão para continuar. Eles são validadores síncronos que interceptam operações antes da execução.

Fluxo de avaliação dos guardas de ação](/pt/blog/img/action-guard-flow.svg)

A interface é 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);
}

Quando ActionName é null, o guarda é executado para cada ação. Quando está definido para algo como "Entry.Publish", apenas intercepta essa ação específica.

O contexto e os contratos de resultado

Cada guard recebe um contexto tipado com o nome da ação, inquilino, utilizador, entidade e um saco de propriedades:

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;
}

E cada guarda retorna um resultado previsível: permitir, negar ou permitir-com-modificações:

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 };
}

O campo Modifications é importante. Um guard pode aprovar uma ação mas reescrever parte do conteúdo (por exemplo, redigir segredos antes de publicar).

Nomes de acções canónicas

Nós definimos todas as ações interceptáveis como constantes de string para que não haja nenhuma ambigüidade sobre o que um guard pode ter como alvo:

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";
    }
}

Exemplo real: bloquear publicação sem aprovação

O plugin Workflow regista um guard 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.");
    }
}

A plataforma principal não sabe nada sobre workflows de aprovação. Apenas chama Entry.Publish através do pipeline, e o guard bloqueia-o se o workflow não tiver sido concluído.

O pipeline de ação: onde tudo converge

O ActionPipeline é o único caminho de execução para todas as operações protegidas. Ele resolve quais guardas se aplicam, avalia-os, e bloqueia ou executa a ação.

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
    }
}

O método EvaluateAsync faz o trabalho 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();
}

Três importantes decisões de design aqui:

Resolução por inquilino O TenantPluginResolver verifica quais os plugins que cada inquilino tem instalados e activados. Um guarda para um plugin desativado nunca é executado.
**Se algum guarda negar, a ação é bloqueada. Esta é uma postura de segurança deliberada.
**Se um guarda lança uma exceção, esta é registada e tratada como Allow(). Isso evita que um plugin quebrado bloqueie toda a plataforma.

Resolução de plugins por inquilino

O resolvedor consulta a tabela TenantPluginInstallations (com escopo automático para o locatário atual pelos filtros de consulta global 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;
    }
}

Efeitos colaterais orientados por eventos

As acções são síncronas. Os efeitos colaterais não são. Depois que uma ação é concluída, o serviço publica um evento de domínio:

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

Os eventos são enfileirados em um canal na memória e processados por um EventConsumerWorker em segundo plano. O trabalhador encaminha os eventos para vários sistemas:

Registo de actividades. Regista quem fez o quê, quando
Faturação da tradução: regista os custos por fornecedor
Manipuladores de eventos de plugins.** Qualquer plugin pode subscrever eventos do domínio

Os manipuladores de eventos de plugins implementam 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);
}

O trabalhador só invoca manipuladores cujo plugin está habilitado para o locatário. Isso significa que os efeitos colaterais do plugin A nunca vazam para um locatário que só tem o plugin B instalado.

O motor de tradução a nível de bloco

É aqui que a arquitetura compensa de forma mais visível.

Tradução por blocos: apenas os blocos alterados são retraduzidos](/pt/blog/img/block-translation.svg)

As plataformas tradicionais traduzem documentos inteiros. Nós traduzimos blocos individuais: parágrafos, títulos, itens de lista. Quando um utilizador edita um parágrafo num documento de 50 blocos, apenas esse parágrafo precisa de ser traduzido novamente. Esta é a fonte da nossa poupança de custos de 94%.

Como os blocos são criados a partir do TipTap JSON

Quando um usuário salva um documento, o editor TipTap envia JSON como este:

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

O BlockTranslationService analisa este JSON e cria registos EntryBlock individuais:

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;
}

hashing SHA256 para deteção de desatualização

O hash de conteúdo é o núcleo da deteção de desatualização. Fazemos o hash do conteúdo do bloco (depois de retirar os atributos de metadados como blockId e deleted) usando SHA256:

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

Quando um bloco de origem muda, seu hash muda. O sistema compara então o SourceContentHash de cada bloco de tradução com o hash de origem atual, e as incompatibilidades são marcadas 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();
}

Adaptação da estrutura

Os tradutores podem alterar os tipos de blocos nas várias línguas. Uma lista de pontos em inglês pode tornar-se numa lista numerada em alemão, uma preferência cultural. O sistema regista este facto:

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

Fornecedores de tradução como plugins

Os serviços de tradução externos (DeepL, Google Translate, etc.) ligam-se atravé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);
}

O método batch recebe um dicionário de IDs de blocos para o conteúdo, traduz todos eles e retorna as traduções com uma contagem de caracteres facturados. Como só enviamos blocos antigos, e não o documento inteiro, os custos são mínimos.

Isolamento do inquilino: a rede de segurança invisível

Todos os sistemas descritos acima funcionam dentro de um isolamento rigoroso do locatário.

O TenantContextMiddleware resolve o inquilino a partir do JWT em cada pedido e verifica a adesão:

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
    }
}

Os filtros de consulta globais do Entity Framework garantem que, mesmo que um programador se esqueça de filtrar por inquilino, a camada de base de dados fá-lo automaticamente:

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

O resultado: db.Hubs.ToListAsync() sempre retorna apenas os hubs do locatário atual. As fugas de dados exigem que se contorne ativamente o filtro de consulta, o que é proibido na nossa base de código.

A imagem completa

Quando um utilizador clica em "Publicar" numa entrada, eis o que acontece:

**A autenticação valida o JWT, TenantContextMiddleware resolve e verifica o inquilino.
**O controlador chama o pipeline.
O pipeline resolve os guardas. Consulta quais os plugins que o inquilino activou, seleciona os guardas aplicáveis.
Os guardas avaliam. O guarda de Fluxo de trabalho verifica as aprovações, o guarda de Retenção verifica a política, o guarda de Regras valida o conteúdo. Todos passam? A entrada é publicada.
**O evento Entry.Published é colocado na fila. Um trabalhador em segundo plano regista a atividade, actualiza a faturação da tradução e chama os manipuladores de eventos do plugin.
Traduções de blocos verificadas. Blocos obsoletos são identificados para retradução.

Cada camada faz o seu trabalho. Nenhuma camada se intromete em outra. Esta é a arquitetura.

Não construímos isto porque a extensibilidade está na moda. Construímo-la porque uma plataforma de documentação que não se pode adaptar ao fluxo de trabalho de cada equipa acabará por ser substituída por uma que o possa fazer. E uma plataforma que se adapta sem proteção acabará por quebrar algo que é importante.