Recebi a tarefa de configurar e gerenciar um ambiente de laboratório totalmente novo, composto por muitas máquinas em diferentes funções. Há um host VM, vários servidores web, vários servidores de banco de dados e outros.
Há necessidades e processos muito específicos que precisam ser documentados como parte deste ambiente de laboratório. Por exemplo, não queremos que as atualizações automáticas do Windows sejam ativadas e há muitas ideias que queremos capturar para explicar a várias partes diferentes ( executivos, gerentes, desenvolvedores, gerentes de TI, pessoal de controle de qualidade).
Então, enquanto estou fazendo a configuração, quero realmente capturar essas conversas em algum tipo de documento formal. Eu ia prosseguir e criar um .doc do Word, organizando cada função de servidor com várias seções distintas:
- Sumário executivo
- Necessidades de manutenção
- Inventário de software instalado
- Hardware disponível
- Padrões de hardware
O que eu gostaria de saber é se existem modelos melhores que eu possa seguir ao criar documentação para essas máquinas. Espero que tudo o que eu acabe criando seja bom o suficiente para que outra pessoa reconstrua as máquinas, se necessário.
Responder1
As coisas mais importantes para um bom sistema de documentação são:
- Fácil de atualizar (ou as pessoas não atualizarão, tornando-o pior do que inútil)
- Fácil acesso - de qualquer local, de vários dispositivos.
- Bem organizado – fácil para as pessoas encontrarem as informações de que precisam e duplicação mínima das mesmas informações.
Eu tentei documentos do Word. Eles falham em todos os 3 pontos. Documentos do Word são difíceis de atualizar, você acaba com pessoas tendo cópias diferentes, etc.
O melhor sistema que encontrei para meu uso é um wiki. DokuWiki funciona muito bem para meus propósitos. Posso acessá-lo e atualizá-lo facilmente de qualquer lugar.
Tenho meu wiki organizado com páginas que descrevem toda a configuração da rede, com links para páginas de cada servidor, cluster e aplicativo. Desta forma, todos os detalhes sobre um item específico são mantidos em páginas separadas e podem ser vinculados a qualquer lugar que seja relevante - quando algo muda, só preciso alterá-lo em uma página e posso encontrar facilmente a informação que procuro. para.
Ele também permite que você especifique modelos de namespace, portanto, quando eu crio uma nova página de servidor, ela é pré-preenchida com tabelas para inserir endereços IP, configuração de hardware, etc. Todos os campos vazios têm FIXME escrito neles, para que eu possa pesquisar em todo o wiki para FIXME e veja o que está faltando na documentação.
Se você realmente quiser ser sofisticado, você pode escrever plug-ins que pegam coisas como arquivos de configuração, analisam-nos e exibem-nos em um formato fácil de ler. Por exemplo, escrevi um plugin chamado PatchPanel que pega uma descrição de texto de um patch panel de rede e desenha uma imagem dele com rótulos para onde cada porta vai.
http://blog.emsley.ca/2014/04/documentation.htmltem um artigo mais completo sobre como eu o configurei (isenção de responsabilidade: link para meu blog, porém completamente no tópico).