Introdução à documentação

Question

Não temos feito nenhuma documentação no meu local de trabalho. Sou completamente novo e peço orientação 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 em sincronia com o sistema? Como você minimiza a duplicação de informações?

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

Answer 1

desde 2003, estou documentando tudo em nosso wiki interno.

Servidores

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

Fluxos de trabalho

por exemplo. como adicionar ou excluir um usuário e dar a ele 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 de intranet / internet / servidor web / etc estiver inoperante

Importante:

Escolha um mecanismo wiki com fácil exportação para PDF!
Não é útil se você está em férias, o servidor rodando seu wiki está inativo e ninguém sabe o que fazer porque sua documentação está off-line

Dê uma olhada no twiki, docuwiki ou mediawiki.

BTW:

existe um plug-in do OpenOffice.org para escrever diretamente para mediawiki - muito conveniente.

EDITAR:

Também é bom anotar algumas informações sobre /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.

    

Answer 2

Enquanto você percebe que, embora todos queiram (e precisem) de 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 uma forma que permita que alguém encontre rapidamente as informações de que precisam, quando precisarem - o que pode acontecer enquanto o sistema estiver inoperante o CTO está respirando no pescoço.

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

• Evite grandes blocos de texto
• As listas de marcadores são suas amigas
• Um diagrama claro é dourado
• Repetição é uma boa ideia (1)
• Facilite a atualização e ampliação

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

    

Answer 3

Documentos essenciais:

• Documentação do servidor - especificações / layouts de disco / software instalado / qualquer coisa de nota
• Procedimentos comuns - tudo o que é feito que não seja "trivial" deve ter um procedimento documentado, especialmente se for algo que não tenha sido feito antes.

Manter a documentação em sincronia pode ser uma questão de 'conserte quando você vê erros'. Juntamente 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 está lá para ajudar um administrador em tarefas, não para ser um conjunto passo a passo de regras que substituem o pensamento crítico.

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

    

Answer 4

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

Pessoalmente, eu me oponho à repetição pelo simples fato de que torna 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 lugar, caso contrário você irá ter uma coleção de documentos conflitantes, o que não ajuda ninguém.

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

    

Answer 5

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

Eu encontrei A Prática de Administração de Sistemas e Redes , de Limoncelli e Hogan (também conhecido como a Bíblia de Sysadmin) para ser bastante valioso, pois trata-se de questões de "melhores práticas", como documentação. Se você ainda não sabe, investigue-o sempre que tiver a chance.

    

Answer 6

Para mim, a consideração mais importante é facilitar o uso. Se é difícil orquestrar, as pessoas irão evitá-lo. Eu escolho o wiki do Trac como meio para nossa documentação, por estas razões:

• Localizado centralmente.

  Mais de uma cópia ativa de qualquer documento gera confusão. Se você conseguir encaminhar todos para o mesmo lugar, tanto para os contribuidores quanto para o público, você poderá simplificar o processo.

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

  Tanto tempo é desperdiçado 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 editá-las quando estiver em movimento, e os contribuidores estarão mais inclinados a fazê-lo. Separe os itens tanto quanto desejar com o TracLinks.

• Histórico de auditoria.

  É importante saber quem fez a mudança, quando e por quê. Se você puder vinculá-lo a tickets de solicitação de mudança e logs de confirmação de configuração, melhor ainda. Ganchos de commit do SVN são ótimos para isso.