*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 ali, 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: **As datas de validade são necessárias e completamente insuficientes. Um documento pode ficar perigosamente obsoleto dias depois da sua última revisão, e uma data de revisão não o vai apanhar.
O 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ê-o, 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
Escreveu um guia de implementaçã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 de revisão, a diferença 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 os maiores danos.
Frescura: monitorização contínua
A pontuação de frescura preenche a lacuna que as datas de validade 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 o nível 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 o conselho ainda é sólido, 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 ser 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 desatualizada, o declínio de leitores - estes 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 desatualizadas 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 expiração 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 surpreendê-lo.
- **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 a sua pontuação de confiança - ou perde-a - em tempo real. Sem espera, sem pontos cegos, sem surpresas no momento 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.