Tópico 10.3 — Gestão do conhecimento e documentação

Em uma frase: Num serviço crítico para a segurança, o que as suas equipes sabem, mas nunca escreveram, é um risco clínico, e não apenas um inconveniente — tratem, portanto, a documentação como um entregável de primeira classe e a continuidade do conhecimento como um dever, e não como uma gentileza.

Por que isso importa na saúde e nos cuidados#

As equipes de saúde digital são pequenas, especializadas e muitas vezes costuradas a partir de funcionários permanentes, prestadores e engenheiros de fornecedores. A pessoa que entende por que a interface de patologia tenta três vezes antes de falhar, ou qual marcador do prontuário eletrônico do paciente suprime um alerta de alergia duplicada, é com frequência um único indivíduo — e esse indivíduo segue adiante, se aposenta ou fica doente na semana em que a integração quebra às 2 da manhã. Quando o conhecimento sai com ele, o sistema não se torna meramente mais difícil de manter; torna-se mais difícil de operar com segurança. Uma gambiarra não documentada em que um clínico confiava pode desaparecer em silêncio, e ninguém que restou sabe que ela era de sustentação.

O que está em jogo é específico do setor. Uma configuração mal compreendida pode produzir um registro do paciente errado, um alerta perdido ou um encaminhamento quebrado — danos medidos em resultados para pacientes, e não em chamados de indisponibilidade. Os órgãos públicos também carregam obrigações estatutárias: os prontuários de saúde devem ser retidos por períodos definidos, e as decisões sobre o cuidado e sobre o dinheiro público devem ser auditáveis anos depois e localizáveis quando um legista, um regulador ou um pedido de Freedom of Information chegar. A boa gestão do conhecimento é, portanto, em parte segurança clínica, em parte governança e em parte respeito pela próxima pessoa que terá de manter o serviço funcionando. É inseparável de como vocês operam o serviço ao vivo (ver Tópico 3.8 — Gestão de serviços e operação em produção) e de como projetam as equipes (ver Tópico 7.0 — Estruturas de equipe, papéis e responsabilidades).

Conceitos centrais#

A gestão do conhecimento como disciplina. A gestão do conhecimento é o conjunto de práticas pelas quais uma organização cria, capta, compartilha e reutiliza o que sabe. Equilibra três componentes — pessoas e cultura, processos e estrutura, e tecnologia — e fracassa sempre que os líderes a tratam como compra de ferramenta e não como hábito. O "conhecimento" vai de como uma via clínica de fato funciona num dado hospital a como um motor de integração específico está configurado.

Conhecimento tácito versus explícito. O conhecimento tácito é o que vive nas cabeças e nas mãos das pessoas — o julgamento, a intuição e o conhecimento duramente conquistado de que "é preciso saber que este hospital codifica a alta de modo diferente", que é difícil de escrever. O conhecimento explícito é o que foi articulado e codificado em documentos, diagramas e manuais de operação. A maior parte do conhecimento que mantém um serviço seguro começa tácita; o trabalho da gestão do conhecimento é converter o suficiente dele em forma explícita para que o serviço não dependa de nenhuma cabeça isolada.

O modelo de conversão de conhecimento SECI. O modelo SECI (Socialização, Externalização, Combinação, Internalização), de Nonaka e Takeuchi, descreve como o conhecimento se move entre as formas tácita e explícita: compartilhar trabalhando lado a lado (socialização), escrever o conhecimento tácito (externalização), combinar peças explícitas em documentos maiores (combinação) e absorver o conhecimento documentado de volta numa prática fluente (internalização). É útil porque lembra que a documentação sozinha não basta — o trabalho em dupla, o acompanhamento e as comunidades importam tanto quanto o wiki.

Dependência de pessoa-chave e o fator ônibus. O fator ônibus (bus factor) é o número de pessoas que precisariam ser perdidas antes que um serviço paralise por falta de alguém que o entenda. Um fator ônibus de um é o estado padrão da maioria das pequenas equipes digitais e um sério risco operacional num serviço de que a saúde das pessoas depende. A alta rotatividade de pessoal, o uso pesado de prestadores e o aprisionamento a um único fornecedor puxam o número para baixo; a documentação deliberada, o treinamento cruzado e o trabalho em dupla o empurram de volta para cima.

A documentação como entregável de primeira classe. Tratem os documentos como produtos, e não como subprodutos. Um manual de serviço descreve o que o serviço é e como se comporta; um manual de operação (runbook) (ou playbook) dá procedimentos passo a passo para iniciá-lo, pará-lo e recuperá-lo; um registro de decisão de arquitetura (ADR) capta por que uma escolha significativa foi feita, para que os futuros mantenedores não a desfaçam sem conhecer as razões. Uma fonte única da verdade significa que cada fato é mantido em exatamente um lugar, para que as pessoas não persigam cópias contraditórias da "arquitetura atual".

Documentação como código (docs-as-code). Manter a documentação no mesmo repositório versionado que o trabalho — escrita em texto simples ou Markdown, revista como código, publicada automaticamente — mantém os documentos perto da coisa que descrevem e muito mais propensos a permanecer atuais. Quando o diagrama vive ao lado do código e muda no mesmo pull request, apodrece mais devagar.

Comunidades de prática. Uma comunidade de prática (às vezes chamada de guilda) é um grupo entre equipes que compartilha um ofício — responsáveis pela segurança clínica, engenheiros de front-end, líderes de governança da informação — e o melhora em conjunto. As comunidades de prática espalham o conhecimento tácito horizontalmente por uma organização que as fronteiras verticais das equipes de outro modo aprisionariam.

Gestão de registros e retenção. A gestão de registros governa a informação ao longo de seu ciclo de vida, incluindo por quanto tempo deve ser mantida e quando pode ser destruída. Na saúde isso é em parte estatutário: os prontuários clínicos carregam períodos definidos de retenção sob o Records Management Code of Practice do NHS. Isso é distinto da documentação da equipe, e confundir as duas causa erros reais — um ponto a que voltamos adiante.

Arquitetura da informação e localizabilidade. A arquitetura da informação é o projeto estrutural de um espaço de informação para que as pessoas encontrem o que precisam. Um wiki com dez mil páginas e nenhuma estrutura não é documentação; é um lixão. A localizabilidade é a diferença entre o conhecimento que existe e o conhecimento que é usado.

Boas práticas#

1. Façam da documentação uma definição de concluído, e não uma reflexão tardia. Uma funcionalidade, integração ou mudança de configuração não está "concluída" até que existam a sua entrada no manual de operação, o seu ADR (se uma decisão significativa foi tomada) e a atualização do manual de serviço. Incorporem isso aos seus modos de trabalho para que seja escrito enquanto o conhecimento está fresco, por quem o detém. Redocumentar um sistema seis meses depois, de memória, é onde nascem as imprecisões e as lacunas perigosas.

2. Mantenham uma fonte única da verdade e remetam a partir dela. Decidam, por domínio, onde mora a versão autoritativa de cada fato — a arquitetura, a escala de plantão, o diagrama de fluxo de dados — e façam todo o resto apontar para ela em vez de copiá-la. A documentação duplicada deriva e, num contexto clínico, uma cópia obsoleta que diz "a verificação de alergia está ligada" quando está desligada é pior do que nenhum documento. Apaguem ou redirecionem implacavelmente as duplicatas obsoletas que vocês já têm.

3. Adotem a documentação como código e mantenham-na ao lado do trabalho. Guardem manuais de operação, ADRs e manuais de serviço em controle de versões junto aos sistemas que descrevem, revejam as mudanças na documentação no mesmo pull request da mudança de código e publiquem automaticamente. Isso torna as atualizações baratas, as mudanças revisáveis e o histórico auditável — e significa que quem muda o sistema é induzido a mudar a documentação no mesmo fôlego.

4. Escrevam manuais de operação que um estranho estressado conseguiria seguir às 3 da manhã. Um manual de operação deve presumir que o leitor está cansado, não familiarizado com o sistema e sob pressão — porque durante um incidente grave estará. Usem passos numerados e literais, nomeiem as telas e os comandos exatos e declarem o resultado esperado de cada passo e o que fazer se ele falhar. Testem-nos pedindo a alguém que não os escreveu que execute uma recuperação num exercício.

5. Captem o "porquê", e não apenas o "o quê", com registros de decisão de arquitetura. Um ADR curto — contexto, decisão, consequências — preserva o raciocínio por trás das escolhas significativas para que os futuros mantenedores não revertam uma decisão sem entender a restrição que a motivou. Na saúde isso importa de forma aguda: uma configuração de aparência estranha pode existir por causa de uma análise de perigos de segurança clínica ou de um parecer de governança da informação. Registrar a razão impede que uma "limpeza" bem-intencionada reintroduza um risco conhecido.

6. Elevem deliberadamente o fator ônibus em todo sistema crítico. Identifiquem os sistemas com fator ônibus de um e tratem isso como um risco no seu registro, com um responsável nomeado e um plano. Façam trabalho em dupla, rodiziem o conhecimento do plantão, realizem sessões de "ensinar de volta" (teach-back), em que o especialista documenta enquanto um colega acompanha, e proíbam que uma única pessoa seja a única capaz de implantar ou recuperar um serviço crítico para a segurança. Isso é mais barato do que descobrir a lacuna durante uma queda.

7. Conduzam revisões pós-incidente que mudem a prática, e não que culpem pessoas. Após qualquer incidente significativo, conduzam uma revisão pós-incidente sem culpa, que produza ações documentadas, com dono e com prazo — e depois de fato as fechem. As lições aprendidas arquivadas e nunca revisitadas são teatro; o teste do processo é se um incidente posterior de mesma forma é evitado. Realimentem os achados diretamente nos manuais de operação e no caso de segurança clínica (ver Tópico 3.8 — Gestão de serviços e operação em produção).

8. Invistam em arquitetura da informação e localizabilidade. Estruturem a sua base de conhecimento para que um novo contratado encontre o manual de operação do plantão em menos de um minuto e podem agressivamente — uma página desatualizada é um passivo, e não um ativo. Acordem convenções de nomes, uma hierarquia clara e um responsável por cada área e ponham uma data de "última revisão" nas páginas que importam para que os leitores julguem o frescor. A busca não substitui a estrutura; complementa-a.

9. Cultivem comunidades de prática para espalhar o conhecimento tácito. Montem guildas entre equipes para os ofícios que importam — segurança clínica, segurança da informação, front-end, engenharia de dados — com uma missão leve: compartilhar o que estão aprendendo, acordar padrões comuns, orientar os recém-chegados. Esses fóruns movem o conhecimento tácito que nenhum documento capta e reduzem a repetição de erros entre equipes (ver Tópico 7.5 — Desenvolvimento de pessoas e da organização). Deem a elas tempo na semana de trabalho, ou murcharão.

10. Separem a documentação da equipe dos registros estatutários — e gerenciem ambos. Sejam explícitos sobre o que é conhecimento da equipe (manuais de operação, ADRs, wikis) versus o que é um registro sujeito a retenção legal (prontuários clínicos, decisões de cuidado, aprovações financeiras, decisões de governança da informação). Apliquem os cronogramas de retenção do Records Management Code of Practice do NHS aos últimos e não deixem a exclusão casual de wiki destruir algo que vocês eram legalmente obrigados a manter. Igualmente, não acumulem tudo para sempre "por segurança" — a retenção excessiva é, em si, um risco de governança e de proteção de dados.

11. Façam da integração de novos funcionários um teste da documentação. Tratem cada integração (onboarding) como uma auditoria viva: se um novo engenheiro ou clínico competente não consegue ficar produtivo a partir do material escrito mais um pouco de trabalho em dupla, a documentação fracassou, e as lacunas que ele encontra são o seu backlog. Peçam aos recém-chegados que corrijam a primeira coisa que os confundiu como primeira contribuição. Isso transforma a integração de custo de mão única num ciclo contínuo de melhoria para a continuidade do conhecimento.

Perguntas para discutir com a sua equipe#

1. Se a única pessoa que entende a nossa integração mais crítica saísse amanhã, quanto tempo até ficarmos expostos — e o que especificamente não saberíamos? Isto transforma a ideia abstrata de fator ônibus num teste concreto de estresse dos seus sistemas mais importantes. Percorram um exemplo real — o feed de patologia, a configuração de login único, a lógica de correspondência do prontuário de cuidados compartilhado — e perguntem com honestidade quem mais poderia operá-lo, alterá-lo e recuperá-lo sem aquela pessoa. A tensão a trazer à tona é que o conhecimento mais profundo costuma estar com o seu indivíduo mais ocupado e mais confiável, e as pressões da entrega tornam racional que ele jamais pare para escrevê-lo. Distingam o conhecimento genuinamente tácito e difícil de codificar do que simplesmente nunca foi captado porque ninguém arrumou tempo. Uma boa resposta, honesta, nomeia em voz alta os seus sistemas de fator ônibus de um, admite quais lacunas são reais e produz um plano com custo definido — trabalho em dupla, sprints de documentação, treinamento cruzado — em vez de uma vaga tranquilização de que "está tudo na cabeça das pessoas e isso é ok". Se a conversa é confortável, vocês não foram específicos o bastante.

2. Quando escrevemos algo, como sabemos que alguém algum dia o encontrará, confiará nele e o manterá atual — e onde a nossa documentação já está mentindo para nós? A documentação desatualizada não é neutra; num ambiente crítico para a segurança, induz ativamente um operador estressado à ação errada. A discussão deve enfrentar a diferença entre ter documentos e ter documentos que as pessoas conseguem encontrar, em que confiam e sobre os quais agem — uma questão de arquitetura da informação, propriedade e frescor, e não de volume. Debatam se a sua base de conhecimento tem uma estrutura real ou virou uma proliferação que ninguém navega e se os documentos vivem perto o bastante do trabalho (documentação como código) para permanecer atuais ou derivam numa ferramenta separada que ninguém atualiza. Perguntem a cada pessoa quando foi a última vez que confiou num documento interno e o achou errado e o que isso custou. Uma resposta forte identifica páginas específicas que vocês sabem estar obsoletas, atribui responsáveis e datas de revisão e acorda uma fonte única da verdade para os fatos que mais importam — e está disposta a apagar mais do que acrescenta.

3. Depois do nosso último incidente grave, o que de fato mudou na forma como trabalhamos — e, se a resposta é "pouco", por que continuamos conduzindo revisões? As revisões pós-incidente são comuns; as que mudam a prática são raras, e a lacuna entre as duas é onde as mesmas falhas se repetem. Isto testa se o seu processo de lições aprendidas é um genuíno ciclo de retroalimentação ou um ritual que produz um documento e nenhuma mudança. Explorem com honestidade as condições culturais: as revisões só trazem à tona a verdade se forem sem culpa, e as pessoas esconderão a causa real se o processo as punir; a segurança psicológica é, portanto, uma pré-condição, e não uma gentileza (ver Tópico 8.1 — Gestão de mudanças). Olhem os seus últimos incidentes e rastreiem cada ação para ver se foi concluída e se evitou a recorrência. Uma boa resposta consegue apontar uma mudança concreta — um manual de operação reescrito, um novo alerta, uma correção de projeto — que uma revisão passada produziu e é franca sobre as ações que foram registradas e abandonadas em silêncio, com um plano para fechar esse ciclo.

4. Quais das coisas que guardamos são registros estatutários que somos legalmente obrigados a manter, quais são notas de trabalho que gerimos pela atualidade — e temos certeza de que não estamos apagando as primeiras nem acumulando as segundas? As organizações de saúde e cuidados carregam deveres de retenção que a maioria das equipes digitais trata por instinto e não por regra, e os erros nas duas direções são reais: apagar casualmente uma página de wiki que se revelou documentar uma decisão de cuidado ou acumular tudo para sempre "por segurança" e criar um passivo de proteção de dados e de localizabilidade. A discussão deve forçar uma linha clara entre um registro sujeito ao Records Management Code of Practice do NHS — prontuários clínicos, decisões de cuidado e de financiamento, pareceres de governança da informação — e o conhecimento da equipe, como manuais de operação e ADRs, que vocês gerem pelo frescor e não pela retenção legal. Tragam à tona os casos intermediários incômodos, como um ADR que documenta por que um perigo de segurança clínica foi aceito, que pode ser ambos. A tensão é que os engenheiros otimizam uma documentação arrumada e atual, enquanto a governança otimiza uma retenção defensável, e os dois instintos puxam em direções opostas. Uma resposta honesta consegue dizer quem é dono do cronograma de retenção, onde a fronteira é traçada e o que aconteceria a um registro específico se fosse solicitado por um legista, um regulador ou um pedido de Freedom of Information anos depois.

5. O que nos nossos modos de trabalho de fato faz a documentação ser escrita enquanto o conhecimento está fresco — e onde ainda dependemos de boa vontade e boas intenções? Toda equipe concorda que a documentação importa; muito menos têm um mecanismo que a faça acontecer por padrão e não por atos heroicos. Esta pergunta sonda se escrever as coisas está engendrado no fluxo de trabalho — uma definição de concluído que bloqueia o "concluído" sem uma entrada no manual de operação ou ADR, a documentação revista no mesmo pull request da mudança, a documentação como código para que o diagrama viva ao lado da coisa que descreve — ou se depende de indivíduos escolherem parar e escrever quando a pressão da entrega diz para entregar. Examinem os incentivos com honestidade: redocumentar um sistema de memória seis meses depois é onde nascem imprecisões perigosas, de modo que o valor está quase inteiramente em captá-lo no momento. Olhem as suas últimas mudanças e perguntem se a documentação foi escrita por quem detinha o conhecimento, na hora, ou acrescentada depois por alguém reconstruindo-a. Uma resposta forte aponta mecanismos concretos já em vigor e nomeia as lacunas em que o processo ainda se apoia na memória e na força de vontade, com um plano para fechá-las.

6. Como movemos o conhecimento que nenhum documento jamais captará — o julgamento e o "é preciso saber que este hospital codifica a alta de modo diferente" — e isso fica mais difícil toda vez que o contrato de um prestador termina? Boa parte do que mantém um serviço seguro é tácita: intuição, reconhecimento de padrões e contexto duramente conquistado que resiste a ser escrito, e o modelo SECI é um lembrete de que a documentação sozinha nunca externaliza tudo. Esta pergunta indaga como vocês deliberadamente espalham esse conhecimento por trabalho em dupla, acompanhamento, sessões de ensinar de volta e comunidades de prática, em vez de supor que o wiki faz o trabalho. A tensão é mais aguda onde vocês dependem de prestadores e de vários fornecedores, porque o conhecimento mais profundo deles sai pela porta no fim de cada contratação, a menos que a captação seja uma expectativa contratual e cultural, e não um favor pedido na última semana. Discutam se os seus ofícios — segurança clínica, integração, engenharia de dados — têm guildas vivas com tempo protegido ou se o aprendizado entre equipes só acontece por acaso. Uma resposta honesta distingue o conhecimento genuinamente tácito, que precisa de transferência de pessoa para pessoa, do meramente não captado e consegue apontar práticas reais — um rodízio de trabalho em dupla, um plano de continuidade do conhecimento para prestadores que saem, uma comunidade de prática ativa — em vez de uma aspiração.

Na prática: um exemplo de saúde e cuidados#

Um sistema de cuidados integrados (ICS) opera um prontuário de cuidados compartilhado que puxa dados de três hospitais de agudos, de serviços comunitários e de um sistema de gestão de casos de cuidados sociais. A integração foi construída há dois anos em grande parte por um engenheiro contratado, "Dev", que entendia toda esquisitice da lógica de correspondência que decide quando dois registros se referem à mesma pessoa. O contrato de Dev termina em seis semanas. Há um wiki, mas foi atualizado de forma significativa pela última vez durante a construção.

A líder de entrega trata isso como um risco de fator ônibus de um e o põe no registro de riscos do programa com o próprio nome ao lado. Ao longo das seis semanas, financia um pequeno esforço de "continuidade do conhecimento": Dev faz trabalho em dupla toda manhã com dois engenheiros permanentes e, em vez de um despejo de cérebro de despedida, eles externalizam pelo caminho — escrevendo manuais de operação para os modos de falha que Dev conhece de cor e ADRs explicando por que a lógica de correspondência tolera certas divergências (revela-se que uma regra aparentemente desleixada existe para evitar um perigo conhecido de segurança do paciente, sinalizado no caso original de segurança clínica). Os documentos vão para o mesmo repositório Git que o código da integração, revistos em pull requests, de modo que são versionados e atuais.

Dois meses depois de Dev sair, o feed de um dos hospitais de agudos começa a produzir registros duplicados de pacientes durante a noite. O engenheiro de plantão — que nunca conheceu Dev — abre o manual de operação, segue os passos numerados, confirma o resultado esperado em cada etapa e restaura a correspondência correta em uma hora. Na revisão pós-incidente sem culpa, a equipe encontra o gatilho (uma mudança a montante na forma como o hospital codifica os números do NHS) e a transforma num alerta de monitoramento e numa atualização do manual de operação. O que teria sido uma correria de vários dias e de alto risco — e um genuíno incidente de segurança do paciente — virou uma recuperação documentada de uma hora, porque o conhecimento tácito foi tornado explícito enquanto a pessoa que o detinha ainda estava lá.

Perspectivas setoriais#

Startup#

Uma startup de saúde digital convive com o maior risco de fator ônibus e a menor folga para tratá-lo: um punhado de engenheiros, conhecimento profundo em cada cabeça e uma cultura que premia entregar acima de escrever. O movimento pragmático é uma documentação leve e barata, incorporada ao fluxo de trabalho — ADRs como curtos arquivos Markdown no repositório, manuais de operação escritos na primeira vez que algo quebra, documentação como código desde o primeiro dia para que o hábito se forme antes que a escala o torne difícil. Os fundadores devem resistir à tentação de adiar toda a documentação para "depois do encaixe produto-mercado", porque uma queda num produto clínico, ou uma avaliação malsucedida de segurança clínica ou do DTAC (Digital Technology Assessment Criteria) por falta de evidências, pode ser existencial. O objetivo não é uma base de conhecimento polida, mas garantir que nenhuma saída isolada possa afundar a empresa.

Pequena empresa#

Um pequeno prestador estabelecido — um consultório de clínica geral, uma farmácia comunitária, uma casa de repouso ou uma clínica de unidade única — carrega os mesmos deveres de segurança clínica e de retenção de registros que um grande hospital, mas sem função dedicada de TI ou de gestão do conhecimento e com pouca folga para construir uma. Aqui a prática deve ser radicalmente proporcional: um lugar localizável para os poucos manuais de operação que importam (como recuperar o sistema clínico, a quem ligar quando o prontuário de cuidados compartilhado falha), um simples arranjo de responsáveis nomeados para que o conhecimento crítico não resida apenas no gerente do consultório ou numa enfermeira de longa data e uma linha clara entre os registros estatutários que são legalmente obrigados a reter e as notas de trabalho que não são. O risco agudo é um fator ônibus de um disfarçado de continuidade: a pessoa que sabe como tudo está configurado é também a que toca o dia a dia, e uma aposentadoria ou uma doença longa pode deixar ninguém capaz de operar um sistema crítico para a segurança. Onde os sistemas são fornecidos e hospedados por um fornecedor, o pequeno prestador deve ainda assim escrever a própria configuração local e as gambiarras, porque o fornecedor não documentará como esta organização de fato usa o produto.

Grande organização#

Um grande hospital do NHS, ICS ou fornecedor de tecnologia em saúde enfrenta a falha oposta: documentação demais, espalhada por SharePoint, Confluence, unidades de rede e e-mail, sem fonte única da verdade e com má localizabilidade. O desafio da grande organização é a arquitetura da informação, a propriedade e a poda — decidir onde cada fato é mantido, atribuir responsáveis, aposentar duplicatas e ligar a gestão do conhecimento à gestão de serviços e ao controle de mudanças. As comunidades de prática justificam aqui seu custo, espalhando padrões por dezenas de equipes que de outro modo aprenderiam cada uma a mesma lição dolorosamente. O risco a gerir é o uso pesado de prestadores e de vários fornecedores, em que o conhecimento sai pela porta no fim de cada contrato, a menos que a captação seja uma expectativa contratual e cultural.

Governo#

Um órgão público nacional ou local — NHS England, DHSC, UKHSA ou uma autoridade local — opera sob deveres estatutários de gestão de registros, obrigações de Freedom of Information e escrutínio de auditoria pública; a gestão do conhecimento é, assim, em parte uma questão de lei e de responsabilização pública. As decisões sobre serviços, dinheiro e política devem ser documentadas, retidas por períodos definidos e localizáveis anos depois para comissões parlamentares, revisões do National Audit Office e inquirições públicas; a história recente das grandes inquirições mostra como o mau registro vira um escândalo em si. O governo deve manter a linha entre os registros estatutários (retidos e descartados por cronograma) e o conhecimento de trabalho (gerido pela atualidade), aplicando com disciplina o Records Management Code of Practice do NHS. A transparência é a palavra de ordem: a premissa de trabalho deve ser que a documentação pode um dia ser lida pelo público.

Modos de falha comuns#

• O herói e o fator ônibus de um. Celebrar o indivíduo que "simplesmente sabe" o sistema sem jamais financiar o trabalho de espalhar esse conhecimento. Parece eficiente até o dia em que ele não está disponível e um serviço crítico para a segurança não tem ninguém que consiga operá-lo.
• Documentação de escrita única. Documentos criados durante uma construção e nunca mais tocados, derivando para uma falsidade confiante. A documentação obsoleta é mais perigosa que nenhuma, porque as pessoas agem sobre ela.
• O lixão do wiki. Milhares de páginas, sem estrutura, sem responsáveis, sem datas de revisão — conhecimento que tecnicamente existe, mas não pode ser encontrado nem aceito como confiável. Volume confundido com valor.
• Documentos longe do trabalho. Documentação numa ferramenta separada que ninguém abre ao programar, o que garante que divirja da realidade. A documentação como código é o antídoto.
• Teatro das lições aprendidas. Revisões pós-incidente que produzem um documento e uma lista de ações nunca fechadas, de modo que o mesmo incidente se repete. O processo vira ritual, e não melhoria.
• Confundir registros com notas. Ou apagar algo que vocês eram legalmente obrigados a reter ou acumular tudo para sempre e criar um passivo de proteção de dados e de localizabilidade. Ambos decorrem de não distinguir os registros estatutários da documentação da equipe.
• Culpa na sala de revisão. Revisões que punem a pessoa mais próxima da falha, o que ensina todos a esconder a causa real e destrói a honestidade de que o processo depende.

Modelo de maturidade#

Lista de verificação#

• Todo sistema crítico tem um manual de serviço, um manual de operação atualizado e ADRs para suas decisões significativas.
• A documentação faz parte da definição de concluído e é revista no mesmo pull request da mudança.
• Cada domínio tem uma fonte única da verdade nomeada; as duplicatas conhecidas são apagadas ou redirecionadas.
• Os sistemas de fator ônibus de um estão no registro de riscos, com responsáveis e um plano ativo de treinamento cruzado.
• Os manuais de operação foram testados por alguém que não os escreveu, num exercício ou num incidente real.
• As revisões pós-incidente são sem culpa e produzem ações com dono e com prazo que são fechadas.
• A base de conhecimento tem estrutura clara, responsáveis de página e datas de revisão; as páginas obsoletas são podadas.
• Existe ao menos uma comunidade de prática ativa para um ofício que atravessa equipes, com tempo protegido para ela.
• Os registros estatutários são distinguidos da documentação da equipe e geridos conforme o cronograma de retenção correto.
• Pede-se aos novos contratados que corrijam a primeira lacuna de documentação que encontrarem como contribuição inicial.

Fontes-chave#

• NHS England / NHSX, Records Management Code of Practice 2021 — cronogramas estatutários de retenção e deveres de ciclo de vida para registros de saúde e cuidados.
• GOV.UK Service Manual (Government Digital Service) — orientações sobre escrever para serviços digitais e operá-los, incluindo documentação e operação de um serviço.
• NHS Digital Service Standard — expectativas para construir e manter serviços digitais sustentáveis e bem documentados.
• Michael Nygard, "Documenting Architecture Decisions" (2011) — o padrão original dos registros de decisão de arquitetura (ADRs).
• Google, Site Reliability Engineering — revisões pós-incidente sem culpa (postmortems), manuais de operação e redução do risco operacional de pessoa-chave.
• Etienne Wenger, Communities of Practice: Learning, Meaning, and Identity (1998) — o texto fundador sobre comunidades de prática.
• Nonaka & Takeuchi, The Knowledge-Creating Company (1995) — o modelo SECI de conversão do conhecimento tácito em explícito.
• A comunidade Write the Docs — orientação de praticantes sobre documentação como código e sobre tratar a documentação como produto.

Referências#

1. Knowledge management — Wikipedia — https://en.wikipedia.org/wiki/Knowledge_management
2. Tacit knowledge — Wikipedia — https://en.wikipedia.org/wiki/Tacit_knowledge
3. Explicit knowledge — Wikipedia — https://en.wikipedia.org/wiki/Explicit_knowledge
4. SECI model of knowledge dimensions — Wikipedia — https://en.wikipedia.org/wiki/SECI_model_of_knowledge_dimensions
5. Bus factor — Wikipedia — https://en.wikipedia.org/wiki/Bus_factor
6. Runbook — Wikipedia — https://en.wikipedia.org/wiki/Runbook
7. Architectural decision — Wikipedia — https://en.wikipedia.org/wiki/Architectural_decision
8. Single source of truth — Wikipedia — https://en.wikipedia.org/wiki/Single_source_of_truth
9. Community of practice — Wikipedia — https://en.wikipedia.org/wiki/Community_of_practice
10. Records management — Wikipedia — https://en.wikipedia.org/wiki/Records_management
11. Information architecture — Wikipedia — https://en.wikipedia.org/wiki/Information_architecture
12. Postmortem documentation — Wikipedia — https://en.wikipedia.org/wiki/Postmortem_documentation
13. Onboarding — Wikipedia — https://en.wikipedia.org/wiki/Onboarding
14. Records Management Code of Practice 2021 — NHS England / NHSX — https://www.nhsx.nhs.uk/information-governance/guidance/records-management-code/
15. Service manual — Government Digital Service (GOV.UK) — https://www.gov.uk/service-manual
16. Documenting Architecture Decisions — Michael Nygard — https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
17. Site Reliability Engineering — Google — https://sre.google/books/
18. Write the Docs — docs-as-code guidance — https://www.writethedocs.org/guide/docs-as-code/