Capítulo 16 — Documentação técnica e segurança

Capítulo 16 — Documentação técnica e segurança

Mapa da aula

Aula 16 publicada. Mapa, exemplo, EX061.

flowchart TD
  N0["16.1 Escrever para o leitor"]
  N1["16.2 Avisos de segurança e de privacidade"]
  N2["16.3 Manter os documentos atualizados"]
  N3["Síntese"]
  N0 --> N1 --> N2 --> N3
  N3 --> EX["Exemplo resolvido"]
  EX --> Q["Exercício EX061"]

Desenho lógico

flowchart LR
  N0["16.1 Escrever para o leitor"]
  N1["16.2 Avisos de segurança e de privacidade"]
  N2["16.3 Manter os documentos atualizados"]
  N3["Síntese"]
  N0 --> N1 --> N2 --> N3 --> Q["EX061"]

[16.1 Escrever para o leitor]
    |
    v
[16.2 Avisos de segurança e de privacidade]
    |
    v
[16.3 Manter os documentos atualizados]
    |
    v
[Síntese]
    |
    v
[Exemplo resolvido] --> [Exercício EX061]

Objetivos de aprendizagem

Você vai (1) escrever documentação técnica clara; (2) incluir avisos de segurança e de privacidade; (3) manter os documentos atualizados.

16.1 Escrever para o leitor

Nadia reescreve as anotações dispersas da Linden num conjunto curto de documentação: um diagrama de rede por clínica, a lista de regras de firewall com os propósitos, as baselines dos dispositivos, os cartões de resposta e runbooks para as tarefas de rotina. Ela escreve para a pessoa que vai usar cada documento sob pressão, muitas vezes um gerente de clínica durante uma indisponibilidade. Cada documento começa com seu propósito e quem deve usá-lo, usa passos numerados e evita jargão. Daniel lembra a ela que a documentação é julgada por se outra pessoa consegue segui-la corretamente sem ajuda.

16.2 Avisos de segurança e de privacidade

Algumas tarefas trazem riscos para os pacientes ou para os dados. Reiniciar o servidor de imagens durante o horário de atendimento poderia interromper um raio X em andamento, então o runbook manda consultar os consultórios primeiro. Exportar logs para uma investigação poderia expor nomes de pacientes, então o runbook manda guardar as exportações apenas na pasta restrita de logs. Nadia coloca os avisos imediatamente antes do passo a que se aplicam, e não numa seção separada, porque as pessoas sob pressão pulam avisos gerais, mas percebem os que estão no lugar onde agem.

16.3 Manter os documentos atualizados

Os documentos envelhecem rápido. Nadia acrescenta uma versão, uma data e um responsável a cada um e liga as atualizações ao procedimento de mudanças: qualquer mudança numa rede, regra ou dispositivo precisa atualizar o documento correspondente antes que a mudança seja encerrada. Grace agenda uma verificação trimestral em que um gerente de clínica segue um runbook e relata os problemas. A primeira verificação encontra uma captura de tela de uma interface de roteador mais antiga. Tratar os documentos como parte do sistema, e não como algo secundário, os mantém úteis quando são mais necessários.

Exemplo resolvido

Nadia escreve documentos focados no leitor, com avisos de segurança e de privacidade junto aos passos, e liga as atualizações ao controle de mudanças e a verificações trimestrais.

Caso sintético. Os documentos e as verificações são sintéticos.

Erros e limites

Os documentos derivam quando as mudanças pulam o procedimento. Avisos demais diluem a atenção.

Exercícios

• EX061 — Teste da documentação. Como a documentação é julgada? Rubrica: 3 = por se outra pessoa consegue segui-la corretamente sem ajuda;; 2 = usabilidade;; 1 = extensão;; 0 = nenhuma.

• EX062 — Aviso sobre reiniciar o servidor de imagens. Que aviso se aplica a reiniciar o servidor de imagens? Rubrica: 3 = consultar os consultórios primeiro para não interromper um raio X;; 2 = consultar os consultórios;; 1 = vago;; 0 = nenhuma.

• EX063 — Onde pôr os avisos. Onde os avisos devem ser colocados? Rubrica: 3 = imediatamente antes do passo a que se aplicam;; 2 = junto ao passo;; 1 = apêndice;; 0 = nenhuma.

• EX064 — Achado da verificação trimestral. O que a primeira verificação trimestral encontrou? Rubrica: 3 = uma captura de tela desatualizada do roteador;; 2 = captura de tela;; 1 = vago;; 0 = nenhuma.

Síntese

Uma boa documentação técnica é escrita para quem a usa, coloca os avisos onde eles atuam e se mantém atualizada por meio do controle de mudanças.

Continue estudando — aula 16 (capítulo 16 de 18)

← Capítulo 15 · Índice das aulas · Capítulo 17 →

Continue para a próxima aula já escrita.