Passos para turno noturno
O que é isso
A maioria dos procedimentos é escrita por quem já conhece o trabalho. Eles são legíveis em uma mesa. Eles falham às 3h da manhã, em uma sala barulhenta, em um telefone, em um segundo idioma, ou quando o leitor tem medo de quebrar algo. As falhas são previsíveis: duas ações escondidas em um passo, um aviso que fica depois do passo que protege, uma condição que aparece no final da frase, uma frase passiva que esconde quem deve agir e palavras como "adequadamente" que pedem ao leitor para adivinhar.
Esta skill transforma esse texto em passos que uma pessoa pode seguir literalmente. Ela empresta a disciplina das linguagens controladas usadas na manutenção de aeronaves e industriais (frases curtas, uma ação por frase, voz ativa, uma palavra para cada coisa), a ordem das mensagens de segurança usada em etiquetas de equipamentos (palavra de sinalização, perigo, consequência, prevenção) e o hábito de escrever um resultado esperado após cada passo arriscado para que o leitor saiba quando parar.
Não é uma passada "para tornar o texto mais humano". O objetivo é um procedimento que não possa ser lido incorretamente, mesmo que soe um pouco simples.
Quando usar
- Runbooks, playbooks de incidentes, listas de verificação de plantão, passos de deploy e rollback.
- Guias de configuração ou reparo para hardware, dispositivos domésticos, equipamentos de laboratório ou TI de escritório.
- Procedimentos operacionais padrão (POPs) e notas de passagem de turno para outra pessoa ou outro turno.
- Instruções que serão traduzidas por máquina ou lidas por falantes não nativos.
- Qualquer texto onde um passo lido incorretamente possa perder dados, dinheiro ou causar ferimentos.
Não use para ensaios, textos de marketing ou explicações conceituais. Esses precisam de uma voz diferente.
As regras (nível padrão)
| # | Regra | Limite ou teste |
|---|---|---|
| R1 | Uma ação por passo | Sem ", então", "e depois", ";" ou dois verbos unidos por "e" dentro de um passo |
| R2 | Frases curtas de instrução | 20 palavras em inglês, cerca de 35 caracteres em chinês |
| R3 | Frases curtas descritivas | 25 palavras em inglês, cerca de 45 caracteres em chinês |
| R4 | Voz imperativa e ativa | Comece com o verbo. Nomeie o ator se não for o leitor |
| R5 | Condição primeiro | "Se a luz estiver vermelha, pare." nunca "Pare se a luz estiver vermelha." |
| R6 | Uma palavra, um significado | Fixe os termos em um glossário. Nunca troque sinônimos por variedade |
| R7 | Valores exatos | Números com unidades, rótulos exatamente como mostrados na tela ou dispositivo |
| R8 | Mensagem de segurança antes do passo | Palavra de sinalização, perigo, consequência, o que fazer |
| R9 | Resultado esperado após passos arriscados | "Resultado: ..." e o que fazer se o resultado for diferente |
| R10 | Sem palavras de adivinhação | Remova "adequadamente", "conforme necessário", "certifique-se", "deveria", "apenas" |
Nível estrito (para texto crítico de segurança ou regulamentado): aplique todas as regras sem exceções, não permita nenhuma hesitação e coloque uma linha de Resultado após cada passo. Nível leve (para uma nota interna que já está razoável): aplique apenas R1, R5, R8 e R9.
Palavras de sinalização
Use a palavra mais baixa que ainda seja verdadeira. Não inflacione.
- PERIGO: causará morte ou ferimento grave se ignorado.
- AVISO: pode causar morte, ferimento grave ou perda de dados ou dinheiro importantes.
- CUIDADO: pode causar ferimento leve ou dano que você pode consertar.
- ATENÇÃO: sem risco de ferimento; apenas risco de propriedade, dados ou tempo.
Toda mensagem de segurança tem três partes: qual é o perigo, o que acontece se o leitor ignorá-lo e o que fazer. "Tenha cuidado" não é uma mensagem de segurança.
Como trabalhar
- Preencha o cartão do procedimento. Antes de editar, escreva: o estado objetivo ("Disco 2 reconstruindo"), quem irá segui-lo (função, idioma, condições como luvas, ruído, tela de telefone, noite), o que eles têm (acesso, ferramentas, tempo), os perigos e as condições de parada. Pergunte ao usuário qualquer coisa que você não puder inferir. Uma condição de parada ausente é a lacuna mais comum.
- Liste os fatos que você deve manter. Cada número, unidade, rótulo, comando, restrição de ordem, aviso e condição. A reescrita deve conter todos eles e não adicionar nenhum. Se você achar que um valor está errado, sinalize-o; não o corrija silenciosamente.
- Divida em ações. Um verbo que o leitor faz = um passo. Navegação conta ("Ir para Armazenamento" e "Selecionar Disco 2" são dois passos). Mova o contexto para um parágrafo curto "Antes de começar".
- Reescreva cada passo. Verbo primeiro, condição primeiro, rótulos exatos em negrito ou
código, unidades sempre. Substitua toda passiva que esconde um ator: "A chave é gerada" torna-se "A ferramenta gera a chave" ou, melhor, o passo que o leitor realiza para gerá-la. - Coloque as mensagens de segurança. Para cada passo que exclui, sobrescreve, desliga, reinicia, desconecta, aquece, corta ou pressuriza, coloque a mensagem diretamente acima do passo. Escolha a palavra de sinalização da escada acima.
- Adicione resultados e saídas. Após cada passo arriscado ou que altera o estado, escreva o que o leitor vê quando funciona. Se o resultado puder diferir, dê uma linha: "Se você vir X, pare e vá para a Recuperação A." Escreva as seções de recuperação.
- Trave o glossário. Escolha um termo por coisa (por exemplo, "bandeja", não "gaveta" ou "suporte"). Salve como
glossary.jsonse o procedimento for mantido. - Linte. Execute
python scripts/stepcheck.py lint procedimento.md --glossary glossary.json. Corrija cada achado UNSAFE e REWORK, ou explique por que um deles é um falso positivo. - Faça uma verificação literal. Leia apenas os passos numerados, como alguém que faz exatamente o que cada frase diz e nada mais. Onde eles parariam, adivinhariam ou fariam algo prejudicial? Corrija esses lugares.
- Retorne o procedimento reescrito, depois uma breve lista de alterações (números das regras), a lista de fatos que você não pôde verificar e perguntas em aberto.
O script auxiliar
scripts/stepcheck.py é um linter Python de biblioteca padrão para procedimentos em Markdown, inglês ou chinês.
| Código | Severidade | Significado |
|---|---|---|
| HAZARD-NO-WARNING | grave | Um passo arriscado não tem mensagem de segurança acima dele |
| LATE-WARNING | grave | A mensagem de segurança está depois do passo que protege |
| WEAK-WARNING | corrigir | A mensagem não diz o que acontece |
| LONG | corrigir | Frase de instrução acima do limite |
| STACKED | corrigir | Mais de uma ação em um passo |
| HIDDEN-ACTOR | corrigir | Voz passiva ou 被 esconde quem age |
| HEDGE / VAGUE | corrigir | Palavras de adivinhação |
| CONDITION-LAST | corrigir | A condição vem depois da ação |
| DRIFT | corrigir | Um sinônimo proibido do glossário |
| NO-RESULT, LONG-DESC | nota | Apenas conselho |
Veredito: PRONTO (saída 0), REFATORAR (saída 1), INSEGURO (saída 2). O script usa listas de palavras e padrões, portanto, ele perde coisas e às vezes sinaliza uma frase correta. Ele nunca substitui o passo 9.
Exemplo
Antes:
- Desligue o NAS se ele ainda estiver funcionando.
- Puxe a bandeja para o Disco 2 e coloque o novo disco nela. CUIDADO: O disco antigo pode estar quente.
Depois:
AVISO: Desligue o NAS antes de remover um disco. Um disco removido enquanto funciona pode corromper o segundo disco. 5. Pressione o botão liga/desliga por 2 segundos para desligar o NAS. Resultado: Todas as luzes da frente se apagam após cerca de 1 minuto. CUIDADO: O disco antigo pode estar quente após o uso. Segure-o pela bandeja, ou você pode queimar os dedos. 6. Puxe a bandeja para o Disco 2. 7. Coloque o novo disco na bandeja.
Alterações: R1 (dividir passo 4), R5 (condição removida ao transformar desligar em seu próprio passo), R8 (aviso movido para cima e com consequência), R9 (resultado adicionado). Os arquivos completos estão em examples/.
Dicas
- Se o texto de origem estiver errado, a reescrita mais clara ainda estará errada. Sinalize valores duvidosos na lista de alterações.
- Mantenha comandos, caminhos e rótulos de tela byte por byte. Uma prosa clara em torno de um comando digitado errado é pior do que o original.
- Um passo que precisa de uma longa explicação geralmente são dois passos mais uma nota antes deles.
- Numere os passos continuamente. Não reinicie a numeração dentro de um procedimento; use seções separadas para recuperação.
- Leia as versões em chinês e inglês lado a lado quando produzir ambas: cada passo deve corresponder um a um.
- Nunca afirme que a saída está em conformidade com qualquer padrão de linguagem controlada oficial. Diga "escrito em um estilo controlado".