Documentação como manual vs. Documentação como lista de verificação

No passado, conversei com outras pessoas do meu departamento sobre documentação, especificamente, nível de detalhe e requisitos. Na visão deles, a documentação é uma lista simples de Y a fazer quando X der errado.

Discordo. Eu acho que isso pressupõe que todos os problemas em TI possam ser facilmente resumidos em simples listas de verificação de procedimentos de recuperação. Eu acho que isso ignora completamente a complexidade da situação, e como as outras pessoas no departamento nem sempre têm um entendimento profundo sobre o problema (é por isso que estou escrevendo o documento - para que elas tenham algo a que se referir) ) que a documentação deve incluir algum material básico de base, como:

• Objetivo do (sub) sistema em questão
• Por que está configurado dessa maneira
• Expectativas de eventos ocorrerem quando as configurações / procedimentos são implementados
• Problemas potenciais que podem causar falhas nos procedimentos

No entanto, sou bastante votado sobre isso, portanto, é necessário que minha documentação seja reescrita em um formulário que diga "As etapas ABC aplicadas na ordem resolverão o problema X". Costumo ouvir o lamento de que ele precisa caber em uma única página de papel. Tente explicar a configuração das Squid ACLs para alguém dessa maneira, incluindo a solução de problemas, através de um documento de uma página. Esse é apenas um dos meia dúzia de documentos que "aguardam para serem gravados" como listas de verificação de recuperação.

O método que estou defendendo realmente está exagerando? Ou eles estão certos, e eu deveria apenas cuidar dos meus negócios aqui e escrever uma lista de verificação simples? Minha preocupação é que, não importa o quão bem você escreva uma lista de verificação de procedimentos, ele realmente não resolva um problema que exige que um SysAdmin pense nas coisas. Se você estiver gastando tempo executando uma lista de verificação de procedimentos de recuperação que acabam não resolvendo o problema (porque existem fatores adicionais que não fazem parte do documento, devido ao foco restrito do documento ) e o objetivo do Como o documento era para evitar reler páginas de manual, wikis e sites mais uma vez, então por que estou analisando as propostas? Estou apenas me preocupando demais, ou isso é um problema real?

EDITAR:

Atualmente, não há posição de helpdesk no departamento. A audiência da documentação seria para os outros administradores ou para o chefe do departamento.

Ao escrever o meu, sempre me dediquei a escrever dois três conjuntos. A lista de verificação de execução, com um apêndice MUITO MAIS LONGO sobre a arquitetura do sistema, incluindo por que as coisas são feitas do jeito que são, pontos de discórdia prováveis ​​ao entrar na Internet e suposições de design abstratas. seguido por uma lista de problemas prováveis ​​e suas resoluções, seguida por uma seção mais longa com informações sobre como um sistema funciona, por que o faz dessa maneira e outras informações úteis para apontar as pessoas na direção certa, caso algo único aconteça.

No meu último trabalho, fomos obrigados a escrever documentos para que mesmo as pessoas do nível 1 do serviço de assistência pudessem trazer as coisas de volta. Isso exigia listas de verificação, que geralmente ficavam desatualizadas em três meses após a redação. É altamente recomendável escrever guias de solução de problemas sempre que possível, mas quando a árvore de contingência tiver mais de três ramificações, você não poderá escrever esse documento sem precisar abstrair.

Ao sair do meu último emprego, entreguei um manual de 100 páginas 'como fazer o meu trabalho' antes de sair. Tinha o material abstrato, filosofia de design e pontos de integração. Como eu provavelmente estava escrevendo para outro administrador de sistemas que iria me substituir, eu o direcionei a alguém que pudesse pegar noções abstratas e transformá-las em ações concretas.

Cinco anos se passaram e acho que minha opinião mudou um pouco. Ambos documento como manual e Documento como Checklist tem lugares muito valiosos na hierarquia de documentação e ambos precisam ser produzido. Eles visam públicos muito diferentes, no entanto.

Documento como lista de verificação

O mercado-alvo desse tipo de documentação são os colegas de trabalho que desejam saber como fazer uma coisa. Eles vêm em dois tipos:

• Colegas de trabalho que só querem saber como fazer algo e não têm tempo para folhear um manual de quinze páginas e descobrir os passos por si mesmos.
• Procedimentos bastante complexos em etapas, mas precisam ser executados de vez em quando.

A impaciência é a causa do primeiro tipo. Talvez o seu colega de trabalho não queira realmente saber por que a saída deve ser canalizada através de um regex perl de 90 caracteres, apenas que deve ser para fechar o ticket. Definitivamente, inclua uma declaração como "Para obter uma explicação detalhada sobre por que esse fluxo de trabalho se parece com isso, siga este link" na lista de verificação para aqueles que desejam saber o porquê.

O segundo ponto é para procedimentos que não são executados com frequência, mas contêm armadilhas. A lista de verificação funciona como um mapa para evitar que a Certa Perdição acabe de voar. Se a lista de verificação for mantida em um repositório de documentação, será necessário pesquisar e-mails durante o tempo em que o administrador antigo enviou um HOWTO.

Na minha opinião, uma boa documentação de lista de verificação também inclui seções sobre possíveis pontos de falha e respostas a essas falhas. Isso pode tornar o documento um tanto grande e desencadear respostas TL; DR em colegas de trabalho; portanto, acho que tornar os modos de falha e suas respostas um link da lista de verificação, e não na página propriamente dita, cria uma lista de verificação desagradável. Abrace a hipertextualidade.

Documento como manual

O mercado-alvo para esse tipo de documentação são pessoas que desejam aprender mais sobre como um sistema funciona. A documentação do estilo "como fazer algo" deve poder ser derivada dessa documentação, mas mais comumente a vejo como um complemento à documentação no estilo de lista de verificação para fazer backup das decisões tomadas no fluxo de trabalho.

Esta é a documentação em que incluímos peças em borracha como:

• Explicando por que está configurado dessa maneira.
  • Esta seção pode incluir questões não técnicas, como a política em torno de como tudo foi comprado e instalado.
• Explicando modos de falha comuns e suas respostas.
• Explicar qualquer contrato de nível de serviço, escrito e de fato.
  • De fato: "se isso falhar durante a semana das finais, é um problema de tudo. Se durante as férias de verão, volte a dormir e lide com isso de manhã".
• Definir metas de atualização e refatoração.
  • A política pode ser diferente mais tarde, por que não corrigimos algumas das más idéias que foram introduzidas no começo?

Tudo isso é muito útil para obter uma compreensão abrangente de todo o sistema. Você não precisa de um entendimento abrangente para executar tarefas simples de automação humana, precisa descobrir por que algo quebrou do jeito que aconteceu e ter uma idéia de onde fazê-lo não fazer isso novamente.

Você também mencionou a documentação da Recuperação de falhas que precisa ser uma lista de verificação.

Eu entendo, você tem minhas simpatias.

Sim, a documentação de DR precisa ser o mais parecida com a lista de verificação possível.
Sim, a documentação de DR é a mais resistente à lista de verificação devido a quantas maneiras as coisas podem quebrar.

Se sua lista de verificação de DR se parecer com:

1. Ligue para Dustin ou Karen.
2. Explique o problema.
3. Afaste-se.

Você tem um problema. Isso não é uma lista de verificação, é uma admissão de que a recuperação desse sistema é tão complexa que é preciso um arquiteto para descobrir. Às vezes, é tudo o que você pode fazer, mas tente evitá-lo, se possível.

Idealmente, a documentação de DR contém listas de verificação de procedimentos para algumas coisas diferentes:

• Procedimentos de triagem para descobrir o que deu errado, o que ajudará a identificar ...
• Procedimentos de recuperação para certos casos de falha. O que é suportado por ...
• Scripts de recuperação escritos com bastante antecedência para ajudar a minimizar erros humanos durante a recuperação.
• Documentação em estilo manual sobre os casos de falha, por que eles ocorrem e o que eles significam.

Às vezes, os procedimentos de triagem são toda a documentação de DR que você pode criar para alguns sistemas. Mas, com isso, significa que a chamada às 4h será mais inteligível e o engenheiro sênior que estiver fazendo a recuperação poderá resolver o problema real mais rapidamente.

Alguns casos de falha têm procedimentos simples de recuperação. Documente-os. Ao documentá-los, você pode encontrar casos em que as listas de comandos estão sendo inseridas em uma ordem específica, o que é um ótimo caso de uso para scripts; ele pode transformar um procedimento de recuperação de 96 pontos em um de 20 pontos. Você nunca descobrirá se pode criar um script até mapear a ação do procedimento de recuperação por ação.

A documentação em estilo manual para casos de falha é a última barreira a ser usada quando não há procedimentos de recuperação ou falha nos procedimentos de recuperação. Ele fornece as dicas do google necessárias para talvez encontrar alguém que tenha esse problema e o que eles fizeram para corrigi-lo.

Na verdade, também não, usamos a Documentação como um Testcase

Dito isto, escrevemos uma documentação que acompanha a documentação como manual . Tínhamos listas de verificação em vigor, mas, ao crescer, achamos que elas eram propensas a erros e realmente falhavam no sistema como um todo.

No entanto, temos o tipo de "Documentação como uma lista de verificação" instalada, ou seja, como mencionado acima, monitoramos extensivamente nossos serviços. Há um ditado:

Se você não está monitorando, não está gerenciando

Isso é totalmente verdade, mas outro deve ser:

Se você não está monitorando, não está documentando

Sempre que precisamos migrar serviços, apenas mantemos o "Grupo de Serviço", "Grupo de Host", o que for aplicável (usamos o Nagios, como você pode imaginar no vocabulário) aberto e ele não é migrado desde que haja um único ponto vermelho em qualquer um dos serviços.

Os testes fornecem uma lista de verificação muito melhor do que qualquer lista de verificação escrita à mão poderia fornecer. Na verdade, é auto-documentado, assim que tivermos alguma falha que não foi monitorada, o teste será pelo menos adicionado ao Nagios, com o que obteremos 2 Coisas de graça:

• sabemos quando falha
• outro ponto da lista de verificação

A documentação "real" é mantida em um Wiki mencionando as probabilidades e os fins do serviço ou teste específico. Se estiver faltando, as pessoas o adicionarão assim que precisarmos fazer alguma migração ou trabalharmos com ela, até agora essa abordagem funcionou muito bem.

Também a documentação errônea é resolvida muito rapidamente, sempre que algo falha, as pessoas começam a procurar a documentação e tentam resolver o problema com os HowTos existentes, se estiver errado, atualize-o com as suas descobertas.

Pense nos erros que você poderia criar seguindo uma lista de verificação e não tendo instalado nenhum teste que fornecerá uma caixa de seleção verde depois de aplicá-los. Eu não acho que é possível separar a documentação do monitoramento.

Depende do público-alvo da sua documentação.

Para tipos de helpdesk (nível 1), uma lista de verificação é o caminho correto a seguir; é claro, isso pressupõe que há níveis mais altos de suporte com o conhecimento mais profundo que você descreve.

Se a documentação for para o grupo de sistemas, eu sempre erro ao lado de mais documentação. Já é difícil ter a documentação adequada apenas para sobreviver, se alguém (você) quiser escrever documentos mais extensos com as informações básicas necessárias - nenhum indivíduo são deve ficar no seu caminho!

Pessoalmente, tento manter a documentação o mais simples possível. Tende a incluir:

• O que [X] deve fazer (requisitos).
• Como [X] foi estruturado em um nível alto (design).
• Por que eu implementei o [X] da maneira que o fiz (considerações de implementação).
• Como a implementação de [X] não é padrão (soluções alternativas).
• Problemas comuns com [X] e como resolvê-los (problemas).

Então, é certo que minha seção de problemas comuns provavelmente será uma breve descrição do que aconteceu e orientações passo a passo sobre como corrigi-lo.

Normalmente, assumo algum conhecimento do leitor do sistema em questão (a menos que seja particularmente misterioso). Não tenho tempo para tornar a maior parte da minha documentação técnica nível 1 ou legível para gerenciamento - mas um nível 3 de pista deve ser bom.

Eu acho que obviamente depende do tópico. Nem tudo pode ser reduzido a uma lista de verificação simples e nem tudo precisa de um manual detalhado do usuário.

Certamente parece que você está falando sobre documentação interna e, na minha experiência, você não pode simplesmente dar uma lista de etapas, porque há muitas opções. Mesmo a criação de uma conta de usuário tem algumas opções (em nosso ambiente), portanto, o documento "Nova conta" lista as etapas básicas em ordem, mas para cada etapa tem uma descrição de quais são as variações.

Por outro lado, nunca escrevemos muito sobre um documento para "Como consertar em um escritório", mas nosso documento muito superficial também não era uma lista de verificação - mencionava a convenção que usamos para as cores dos cabos, enfatizou que você tinha que atualizar a planilha que listava as conexões, e era isso.

Então, agora que escrevi isso, concordo totalmente: listas de verificação passo a passo simplesmente não serão suficientes para muitos processos.

Concordo plenamente com você (em favor de documentação exaustiva) em parte porque estou acostumado a ter predecessores que NÃO tinham muito interesse em documentos. Como já foi dito em posts relacionados, redigir não é apenas bom para os outros, mas ajuda a entender melhor o seu ambiente e solidificá-lo em sua própria mente. É um fim em si mesmo.

Como um aparte, acho que grande parte da reação vem de uma crença estranha de que documentação ruim / inexistente = segurança no emprego. Esse tipo de pensamento parece desonesto e obscuro.

Parabéns a você por contrariar o status quo.

Documento bastante, tenho até uma lista de verificação de prioridade de documento :-), no entanto, não documentarei coisas que possam ser consideradas conhecimentos genéricos (ou seja, uma boa descrição razoável do problema fornece uma resposta na primeira página do google).

Para quem estiver interessado aqui, é minha lista de verificação doc prio (funciona para mim, talvez não seja para você, comentários e sugestões são muito apreciados):

1. Crie um diário / diário pessoal em que você anote tudo o que trabalhou / conhecimento
2. Serviços, qual serviço é onde, o que faz e para quem é feito (qualquer contrato de SLA? Deve ser criado?)
3. Servidores, de que servidor é onde, com que idade e quando é escrito
4. Como acima, mas para equipamentos de rede, UPS e similares
5. Como acima, mas para todas as máquinas do usuário
6. Layout da rede física (qual cabo vai para onde, quanto tempo é e qual é a qualidade medida)
7. Visão geral da configuração de software e licenças para servidores
8. Visão geral da configuração de software e licenças para máquinas do usuário
9. Visão geral da configuração de switches, roteadores e outro hardware dedicado
10. Contratos e SLA de todas as partes externas para as quais meu serviço depende diretamente (ISP, domínio etc.)
11. Configure um sistema de tickets com wiki integrado para colocar todas as coisas acima.
12. Para cada incidente, crie um ticket (mesmo que você o use apenas para si).
13. Crie um script que no domingo reúna tickets e os agrupe no tipo de problema.
14. Na segunda-feira, crie uma solução automática ou um documento de instruções do usuário final para o problema mais ocorrente
15. Se o tempo permitir, faça o próximo.
16. Se não houver mais nada a fazer, procure um novo emprego e dê à pessoa que o substitui o log ;-)

Uma lista de verificação é boa, desde que não esteja pretendendo ser uma documentação completa . Os últimos documentos que escrevi foram divididos em duas partes: XYZ for Users, que incluía capturas de tela bonitas sobre como usá-lo; e XYZ para administradores de sistema, que incluiu como foi configurado e por que (possivelmente incluindo o requisito de negócios para ele existir), interceptações a serem evitadas e uma seção sobre solução de problemas. A solução de problemas é onde eu esperaria encontrar as listas de verificação. Talvez escrever as listas de verificação como XYZ for Tech Support possa ajudar a fazer uma observação.

Agora, lendo nas entrelinhas, focar apenas em listas de verificação indica para mim uma falta de pensamento "abrangente" e planejamento a longo prazo que eu esperaria de alguém que: apenas fez suporte técnico; ou um administrador júnior apenas começando; ou está tão cheio de trabalho que não tem tempo para pensar nisso; ou nunca foi levado a pensar nisso; ou simplesmente não se importa. Não sei qual deles, se houver, se aplica ao seu caso.

Eu sou muito grande em documentação. A empresa em que trabalho agora considera que a documentação é importante, mas algumas pessoas na empresa sentem que não têm tempo para escrever a documentação. Isso pode dificultar a vida de qualquer pessoa além da pessoa que originalmente a fez.

Para certas coisas, escrevi instruções passo a passo. Você pode chamar isso de lista de verificação, se quiser, mas não se destina a ser fisicamente marcado. Eu chamo meu estilo de documentação de "etapas do jardim de infância". É modelado após um caderno de exercícios do MCSE que eu tinha para um dos exames do Windows 2000. As etapas são muito detalhadas, mas o uso de negrito / itálico / tipo de letra facilita a visualização e apenas seleciona as partes importantes para que você não precise ler tudo depois de aprender as etapas.

Algumas coisas não são adequadas para instruções passo a passo, por isso tento fornecer o máximo de dados de configuração possível. Uma pessoa tecnicamente inclinada que acaba mantendo a estrada terá uma idéia melhor do que está enfrentando e, com sorte, isso facilitará a vida deles quando algo der errado.