Capítulo 16 — Documentação técnica e segurança
Mapa da aula
Aula 16 publicada. Mapa, exemplo, EX061.
flowchart TD
N0["16.1 Runbooks"]
N1["16.2 Avisos de segurança"]
N2["16.3 Versionamento"]
N3["16.4 Aposentadoria"]
N4["16.5 Público"]
N5["16.6 Ritmo de revisão"]
N6["16.7 Capturas de tela nos runbooks"]
N7["16.8 Tradução"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
N7 --> EX["Exemplo resolvido"]
EX --> Q["Exercício EX061"]
Desenho lógico
flowchart LR
N0["16.1 Runbooks"]
N1["16.2 Avisos de segurança"]
N2["16.3 Versionamento"]
N3["16.4 Aposentadoria"]
N4["16.5 Público"]
N5["16.6 Ritmo de revisão"]
N6["16.7 Capturas de tela nos runbooks"]
N7["16.8 Tradução"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX061"]
[16.1 Runbooks]
|
v
[16.2 Avisos de segurança]
|
v
[16.3 Versionamento]
|
v
[16.4 Aposentadoria]
|
v
[16.5 Público]
|
v
[16.6 Ritmo de revisão]
|
v
[16.7 Capturas de tela nos runbooks]
|
v
[16.8 Tradução]
|
v
[Exemplo resolvido] --> [Exercício EX061]
Objetivos de aprendizagem
Você vai (1) escrever runbooks para verificações autorizadas; (2) manter visíveis os avisos de segurança; (3) versionar documentos; (4) aposentar métodos obsoletos.
16.1 Runbooks
Passo a passo para cada verificação recorrente, com referências às ROE e as condições de parada no topo, em negrito. O runbook do ENG-512 cobre a abertura, os cartões de método, as mensagens de parada e a limpeza. Cada chamado cita o hash git do runbook, e cada colega cola o mesmo hash no próprio caderno na abertura, como recibo. Assim, todos trabalham a partir de uma única versão dos capítulos de abertura e de parada, e uma edição posterior do runbook não pode deixar dois técnicos seguindo regras de parada diferentes na mesma janela de sábado.
16.2 Avisos de segurança
"Não execute contra a produção" é a primeira linha do runbook de comparação de portas da homologação. A primeira página de todo runbook traz os avisos de segurança: a rede de tarifas é preta e a varredura livre é proibida. As amostras de auditoria sempre abrem primeiro a página um, e um runbook cujo aviso de tarifa aparece só numa página tardia reprova na amostra e tem o chamado reaberto. Avisos enterrados na página nove não protegem ninguém, porque um técnico sob pressão de tempo lê os passos iniciais e raramente o apêndice.
16.3 Versionamento
Os documentos mostram versão, data e responsável; as versões antigas são arquivadas. As versões dos runbooks são acompanhadas por tags do git, e Sam não segue uma cópia impressa mais antiga que a tag nomeada nas ROE. A lista de abertura inclui um git describe contra essa tag; se a saída não confere, a abertura é cancelada até que a cópia seja alinhada. Uma página impressa pode ser conveniente na mesa, mas só a versão com tag vale quando uma regra de parada ou um contato mudou.
16.4 Aposentadoria
Métodos que usavam ferramentas aposentadas são marcados como obsoletos, para que os iniciantes não os sigam. A aposentadoria também remove cartões que mencionam hosts desativados. Esses cartões vão para o arquivo na mesma semana em que o host é desativado, para que uma verificação vencida não volte à pilha no sábado seguinte. Deixar páginas aposentadas na biblioteca ativa confundiria a próxima janela, porque um iniciante poderia seguir um método dirigido a um host que não existe mais ou que agora pertence a outra pessoa.
16.5 Público
Escreva para um técnico que estava doente durante o último engajamento. Os leitores são técnicos e o SOC, e não o marketing, então cada passo é escrito para que um técnico que perdeu o ENG-512 consiga segui-lo à noite sem ligar para Sam. As condições de parada aparecem em palavras simples, com um exemplo da mensagem de interrupção a publicar. Slogans e elogios a ferramentas são cortados antes de a edição para técnicos ser publicada, porque aumentam o tamanho sem ajudar ninguém a decidir o que fazer.
16.6 Ritmo de revisão
Os runbooks são revistos a cada seis meses ou depois de qualquer incidente de parada. Uma mudança de arquitetura também dispara uma revisão, mesmo quando a data de seis meses ainda está longe. Uma revisão perdida abre um chamado de dívida do programa, que tem responsável e prazo como qualquer achado, e o pacote do CISO lista a dívida de documentação em aberto ao lado dos achados técnicos. Tornar a dívida visível impede que runbooks desatualizados derivem em silêncio até que o próximo incidente de parada os exponha. Cada revisão é registrada com a tag de runbook que produziu, para que os leitores vejam quando uma página foi confirmada pela última vez.
16.7 Capturas de tela nos runbooks
Os runbooks preferem passos em texto a capturas de tela que envelhecem quando a interface muda. Onde as capturas ajudam, elas são datadas. Todas as capturas de tela dos runbooks são sintéticas e mascaradas; telas reais de passageiros nunca ilustram um procedimento. A mesma integração contínua que monta os materiais do curso rejeita pull requests que acrescentam capturas não sintéticas de passageiros, para que a política não dependa de os revisores perceberem. Figuras sintéticas ainda mostram os passos com clareza e eliminam o risco de que um documento de treinamento vire um depósito acidental de dados pessoais de passageiros.
16.8 Tradução
Se um turno de terceirizados fala outra língua, os avisos críticos de parada aparecem nas duas línguas usadas no local. A redação das frases de parada é combinada uma vez com o SOC e depois reaproveitada, em vez de improvisada durante um incidente. Empatia improvisada ou redação atenuada numa mensagem de parada não é um controle. As frases de interrupção combinadas são versionadas ao lado do trecho da carta de ética, então qualquer edição nelas precisa dos mesmos responsáveis que uma edição no texto de ética e não pode entrar despercebida entre as janelas.
16.9 Disciplina de campo
Quando acontece um incidente de parada, Sam atualiza o runbook na mesma semana ou registra um chamado explicando por que não. Documentação adiada para "depois do período corrido" é documentação que nunca acontece. Seus gestores aceitam runbooks mais curtos e atualizados em vez de longos que descrevem ferramentas aposentadas. A disciplina de campo para a documentação é versionada, com avisos, aposentadoria limpa e capturas sintéticas. O ENG-512 de Sam depende do runbook com tag, e não da memória. Um runbook que não pode ser seguido sem perguntar a Sam é tratado como inacabado, seja qual for seu tamanho ou acabamento.
16.10 Nota de encerramento
Runbooks obsoletos vão para uma pasta /archive, e a integração contínua verifica que nenhum link ativo aponta para ela. Links quebrados para métodos aposentados reprovam o build da documentação. A documentação é o modo pelo qual a NMT sobrevive às férias de Sam. Um substituto precisa encontrar no runbook as frases de parada e a exclusão da tarifa sem perguntar a Sam, então uma frase de parada ausente é tratada como defeito, e não como escolha de estilo. Quando os documentos estão completos e atualizados, o programa pode continuar testando com segurança enquanto o líder habitual está de licença.
16.11 Extra
Sam imprime a página de condições de parada do runbook ativo e a mantém na mesa durante as janelas — telas bloqueiam, e o papel continua legível quando os segundos importam. Como extra, Sam mantém uma folha de consulta de uma página do ENG-512 colada ao lado do jump host. Ela traz a data das ROE, os contatos de emergência e a exclusão da tarifa, e é substituída sempre que a data das ROE avança. Uma folha que corresponde às ROE vigentes dá ao técnico os limites essenciais num relance, sem abrir um documento enquanto uma parada está em andamento.
Exemplo resolvido (NMT sintética)
O runbook v1.3 de Sam abre com STOP CONDITIONS e OUT OF SCOPE: fare network, e só depois vêm os passos da comparação de portas.
Caso sintético — Northline Municipal Transit (NMT). A operadora de transporte, Sam Park e todos os números foram inventados para fins didáticos.
Erros e limites
Sistemas de transporte reais e equipamentos de tarifa nunca são testados sem uma autorização separada e especializada. Este livro usa apenas dados sintéticos e não concede autorização para testar sistemas reais.
Exercícios
- EX061 — Topo do runbook. Quais dois blocos ficam no topo? Rubrica: 3 = condições de parada e ROE/fora do escopo; 2 = um; 1 = histórico; 0 = nada.
- EX062 — Primeira linha. Qual é a primeira linha do runbook de comparação de portas da homologação? Rubrica: 3 = não executar contra a produção; 2 = parcial; 1 = instalar a ferramenta; 0 = nada.
- EX063 — Obsoleto. O que deve acontecer com um runbook de uma ferramenta aposentada? Rubrica: 3 = marcar como obsoleto/arquivar; 2 = parcial; 1 = deixar como está; 0 = nada.
- EX064 — Gatilho de revisão. Quando os runbooks precisam ser revistos fora do ritmo de seis meses? Rubrica: 3 = depois de um incidente de parada (ou de uma grande mudança); 2 = parcial; 1 = nunca; 0 = nada.
Síntese
A documentação põe a segurança em primeiro lugar, continua versionada e se aposenta junto com suas ferramentas.
Continue estudando — capítulo 16 de 18
← Capítulo 15 (rascunho) · Índice de capítulos do curso · Capítulo 17 (rascunho) →