Como você evita que a documentação do servidor fique fora de sincronia com a configuração real?

Temos uma documentação razoavelmente boa para o nosso ambiente (no formato AsciiDoc), que recentemente permitiu a outra pessoa recriar toda a instalação do zero em menos de 30 minutos.
No entanto, notei que após a configuração inicial, acontece facilmente que pequenas alterações feitas no sistema (digamos: inetd ficam desabilitadas, meu servidor IMAP escuta uma porta adicional para conexões do ManageSieve, um novo roteador é adicionado à configuração do exim) acabe na documentação imediatamente (se houver).

Minha idéia era evitar esse problema gerando (parcialmente?) A documentação dos arquivos de configuração e os comentários nele contidos - uma maneira de implementar isso pode ser colocar /etce /usr/local/etcentrar em algum sistema de gerenciamento de código-fonte (por exemplo, git) e executar um script que regenera a documentação em cada confirmação. No entanto, não tenho certeza se isso seria um exagero e / ou muito difícil de acertar (afinal, não quero cópias completas dos arquivos de origem na minha documentação, mas apenas as diferenças).

Como as outras pessoas evitam que a documentação do servidor fique desatualizada - existe uma boa maneira de mantê-las sincronizadas automaticamente ou você apenas tem a disciplina de atualizar a documentação ao mesmo tempo em que modifica o sistema?

Você nunca vai se afastar de alguma documentação, mas, como sugeriu, existem sistemas que podem ser integrados ao seu processo de mudança para cobrir grande parte dela.

• Use uma ferramenta de gerenciamento de configuração (como fantoche ou chef ).
• Armazene sua configuração de maneira controlada por alterações. (como git ou SVN )
• Verifique se a configuração é legível / acessível por humanos (por exemplo, texto sem formatação, banco de dados pesquisável)

Dessa forma, a documentação de nível inferior que normalmente não temos (ou não nos preocupamos) é aplicada armazenando essas informações nos itens ou código de configuração como parte do sistema em que você está fazendo alterações. Isso também tem um bônus adicional do processo, tornando-se mais repetível no futuro.

A documentação externa ainda precisa ser atualizada, mas se torna muito alto com ponteiros para "implantar x" ou "implantar y" em vez de longas listagens de comando / arquivo. Além disso, isso faz com que as alterações na documentação sejam menos frequentes e mais fáceis, o que também significa que será mais provável que isso seja feito.

Também antes de você ir para casa, com o fantoche, alguém provavelmente já escreveu algo para gerenciar o que deseja.

Se você administra apenas um ou dois pequenos sistemas, a configuração de um grande sistema de gerenciamento de configurações, como fantoche ou chef, parece um exagero. (Porém, se você planeja ter mais sistemas no futuro, faça-o agora!)

Para uma configuração pequena como essa, recomendo usar algo como etckeeper, um programa que coloque /etcem um gitrepositório e ofereça algumas funções úteis, como realizar uma confirmação automática sempre que você instalar, atualizar ou remover um pacote.

Você só precisa atualizar sua documentação toda vez que fizer uma alteração no sistema. AKA Change Management.

O fato de a maioria das empresas implementar o gerenciamento de mudanças de maneira tão ridícula que o torne pior do que nada não deve prejudicar a utilidade do conceito básico ou impedir que você faça o que é correto.

Eu costumava usar htmlou algum tipo de wiki para rastrear todas as minhas configurações. Agora, trabalho em uma loja do Windows com o SharePoint ( estremecedor ), e agora uso os "modelos" do documento do Word que criei para rastrear todos os sistemas que possuo e todas as alterações de configuração que faço, o que não é tão ruim quanto parece, pois muitos sistemas são apenas cópias de outros que podem ser agrupados no mesmo documento. (E eu mantenho cópias locais de todas as minhas coisas, meu disco rígido, organizado de maneira sensata, além de jogá-las no monte desorganizado que é o site de qualquer pessoa do SharePoint.)

O maior desafio é realmente reservar um tempo para documentar, o que eu faço adicionando o tempo da documentação como parte do tempo para fazer a alteração. Portanto, não é tão difícil assim, especialmente se você é um idiota e não se importa de dizer às pessoas para se ferrar e esperar na fila, porque você está ocupado demais para o problema deles no momento.