Introdução à documentação

Nós não temos feito nenhuma documentação no meu local de trabalho. Sou completamente novo e peço algumas orientações para começar.

Eu tenho algumas perguntas:

• Quais são os documentos essenciais que um administrador de sistemas deve escrever e manter? E por que isso é tão importante?

• Como você mantém sua documentação sincronizada com o sistema? Como você minimiza a duplicação de informações?

• Guias recomendados, melhores práticas, antipadrões?

desde 2003 estou documentando tudo em nosso wiki interno.

Servidores

• especificações de hardware
• informações de garantia
• informação de rede
• e, é claro, software e configuração instalados

Fluxos de trabalho

por exemplo, como adicionar ou excluir um usuário e dar acesso a todos os serviços relevantes

Links importantes

• link para todas as suas interfaces da web
• link para os URLs de monitoramento (nagios, munin, apc-Monitoring ...)
• link para o wiki (para a versão impressa!)

Instruções de emergência

o que fazer se o servidor da intranet / Internet / servidor da Web / etc estiver inativo

Importante:

Escolha um mecanismo wiki com fácil exportação para PDF!
Não é útil se você estiver de férias, o servidor que está executando o seu wiki está inoperante e ninguém sabe o que fazer porque sua documentação está offline

Dê uma olhada no twiki, docuwiki ou mediawiki.

BTW:

existe um plugin do OpenOffice.org para escrever diretamente no mediawiki - muito conveniente.

EDITAR:

Também é bom escrever algumas informações /home/adminuser/maintenance. Isso é feito rapidamente e pode ser muito útil, se vários administradores trabalharem em um servidor. por exemplo:

2009-06-27 -thorsten-
          running aptitude update && aptitude full-upgrade
          everything seems ok
2009-06-25 -andreas-
          cups-pdf wasn't reachable. restarted cups
2009-06-23 -thorsten-
          deleted old log under /var/log/squid
etc.

Enquanto você percebe que, embora todos desejem (e precisem) documentação, você também precisa reconhecer que ninguém tem tempo para ler e estudar as coisas.

Portanto, não escreva documentação que precise ser estudada - em vez disso, estruture sua documentação de maneira que alguém possa encontrar rapidamente as informações de que precisa, quando precisam - o que pode acontecer enquanto o sistema estiver inativo e o CTO estiver respirando pelo pescoço.

Com isso em mente, algumas sugestões ...

• Evite grandes blocos de texto
• As listas de marcadores são seus amigos
• Um diagrama claro é dourado
• Repetir é uma boa ideia (1)
• Facilite a atualização e a extensão

(1) Não crie uma fonte de verdade e force as pessoas a procurá-la. Quanto mais importante a ideia, mais você deve repeti-la.

Documentos essenciais:

• Documentação do servidor - especificações / layouts de disco / software instalado / qualquer coisa a ser observada
• Procedimentos comuns - tudo o que é feito que não é 'trivial' deve ter um procedimento documentado, especialmente se for algo que nunca foi feito antes.

Manter a documentação em sincronia pode ser bastante um "conserte-o à medida que você vê erros". Junto com isso, é necessário perceber que a documentação pode e estará desatualizada e que não deve ser seguida cegamente sem levar isso em conta. A documentação existe para ajudar um administrador nas tarefas, não para ser um conjunto passo a passo de regras que substituem o pensamento crítico.

Minimizando a duplicação - usar algo como wikis onde você pode vincular a documentação pode ajudar com isso, em vez de repetir informações, basta vincular a ela. O problema é que a pessoa que está escrevendo a documentação precisa saber que as informações que estão prestes a duplicar já existem. Isso geralmente é uma questão de boa organização.

Descobri que criar um modelo é uma grande ajuda. No meu caso, é um modelo do Word, mas use o que você desejar. Crie um arquivo esqueleto, completo com o campo e seções do índice, conforme desejado. Depois de usá-lo algumas vezes e de fazer alguns ajustes, você criará novos documentos muito mais rapidamente. A consistência do formato será uma grande ajuda, tanto para a criação de documentos quanto para uso posterior. A documentação precisa ser armazenada em um local lógico e em uma estrutura de diretórios lógicos.

Pessoalmente, sou contra a repetição pelo simples fato de tornar a manutenção desnecessariamente difícil e demorada. Em vez de duplicar documentos, ou partes de documentos, crie referências a outros documentos, quando apropriado. Se algo mudar, você nunca precisará alterar a documentação relevante mais de uma vez ou em mais de um local; caso contrário, você terá uma coleção de documentos conflitantes, o que não ajudará ninguém.

Ao criar sua documentação, lembre-se de para que serve. Alguém mais tarde precisará usá-lo. Será útil fazer o trabalho sem conhecimento prévio?

Não é uma resposta direta à sua pergunta, mas um ponteiro na direção certa:

Achei The Practice of System and Network Administration , de Limoncelli e Hogan (também conhecido como Bíblia Sysadmin), bastante valioso porque se trata de questões de "melhores práticas", como documentação. Se você ainda não sabe, investigue-o sempre que tiver a chance.

Para mim, a consideração mais importante é facilitar o uso. Se for difícil orquestrar, as pessoas o evitarão. Eu escolhi o wiki do Trac como o meio para nossa documentação por estes motivos:

• Centralmente localizado.

  Mais de uma cópia ativa de qualquer documento gera confusão. Se você conseguir encaminhar todos para o mesmo local, colaboradores e público-alvo, poderá simplificar o processo.

• Edição e formatação simples.

  É desperdiçado muito tempo em belos modelos do Word e em conformidade com o estilo do último autor. Se você não atrapalhar as pessoas com isso, será mais fácil editar em qualquer lugar e os colaboradores estarão mais inclinados a fazê-lo. Separe os itens o quanto desejar com o TracLinks.

• Histórico de auditoria.

  É importante saber quem fez o que mudou, quando e por quê. Se você pode associá-lo a tickets de solicitação de mudança e logs de confirmação de configuração, é ainda melhor. Os ganchos de confirmação do SVN são ótimos para isso.