Métodos para criar uma boa documentação administrativa?

Question

Eu quero documentar qualquer alteração que eu faça no meu sistema Ubuntu. Eu quero fazer isso de uma forma que se eu tivesse que passar este sistema para outro administrador, seria fácil e lógico para ele acessar essa documentação e usá-la para qualquer propósito. A principal razão que eu quero fazer isso é para que eu possa olhar para trás e ver exatamente o que é feito para resolver um problema e assim por diante.

Qual seria a melhor maneira de fazer isso? Eu estou pensando colocação dos arquivos de documentação e métodos de criar e visualizá-los facilmente.

Outra razão pela qual eu quero aprender uma boa documentação é que um dos livros do LPIC-1 diz que isso é muito importante, mas não elabora muito sobre o assunto.

Espero que esta questão não seja distribuída de forma independente ou pouco clara.

Atualização: (fez algumas ideias e mais pensamentos sobre o assunto)

Tenho um Dell Inspiron 1564 com placa sem fio BCM4312 na qual o driver Broadcom Sta / wl causou pânico no kernel. Não me lembro de tudo o que tentei consertar e não me lembro como exatamente resolvi o problema. Eu também tenho problemas com meu novo driver, e sinto falta de não ter documentado isso localmente.

O que eu quero, é uma pasta que contém tanto documentação sobre o que foi feito, o que está instalado no sistema e também talvez HOWTOs para novos usuários de desktop. Eu quero um pager, como less para exibir esses arquivos, e eu quero usar um bom local para armazená-los. (usr / share / doc?) Isto é, além de comentar em arquivos de configuração e scripts.

Eu também quero criar uma função que liste toda a documentação. Eu acho que preciso escrever um script, com opções para criar, imprimir e listar meus arquivos doc. Eu estou no caminho certo em tudo aqui?

Eu acho que não é realmente necessário escrever um roteiro para isso, mas acho que pode ser um bom aprendizado, de qualquer forma. Estou pensando em algo simples assim:

• lista de arquivos de documentos #To list all doc files and howto files.
• docfile -n ou nome do arquivo.howto #Create new/edit file doc tile
• docfile #View file in pager like less

Sim, eu tenho algum tempo em minhas mãos no momento ..:)

Para reduzir a questão ao osso: quero uma maneira simples e elegante de criar e imprimir documentação localmente. A sugestão acima (um script) é uma maneira razoável de resolver isso? E onde devo colocar esses arquivos? É / usr / source / doc / docfiles o lugar para salvá-los?

    

Answer 1

Crie um script.

Temos um script de pós-instalação para quando precisamos instalar um novo servidor. Depois que o servidor básico do Ubuntu é instalado, fazemos uma instalação semi-automática do apache, mysql e outros softwares. Em seguida, extraímos uma imagem com nosso software e configurações para o apache (ou seja, habilitado para o site) e o mysql (ou seja, my.cnf).

A parte divertida do Linux é que qualquer coisa é um arquivo, então este script também tem muitas instruções "sed" que alteram os arquivos de configurações da linha de comando. Pense nas linhas de ajustes de desempenho, tarefas agendadas em /etc/crontab , nossos próprios arquivos de log.

Os comentários acima dos comandos garantem que alguém possa entender o que está acontecendo.

Ter essas coisas no papel só funciona na teoria, mas depois de um tempo é inútil, uma vez que as pessoas esquecem de atualizar as mudanças que elas fizeram ... tê-las em um script fará com que todos atualizem esse script (pois facilita o trabalho deles).