October
15

Documentar é o que há

Posted In: Cotidiano, GTI, Linux by Edgar Gabaldi

Do que adianta fazer aquele bolo delicioso se você joga a receita fora? Documentar é uma tarefa importante sim, e 90% dos administradores de sistemas e redes ignoram.

Documentar é uma tarefa trabalhosa e com o passar do tempo, uma documentação bem elaborada e atualizada vai salvar sua pele ou até mesmo seu emprego.

Acima de tudo temos que ser profissionais, nunca reter o conhecimento conosco. Somos seres humanos e estamos a qualquer momento sujeitos a doenças, imprevistos e sinistros que impeçam de uma hora para outra você de continuar seu papel na empresa.

Basicamente existe dois tipos de documentação:

Documentação do Servidor:

  • É importante ter todos os arquivos de configuração que estão funcionando documentados. Quem nunca passou raiva ao pegar scripts e arquivos de terceiros totalmente bagunçados?
  • Também é importante ter toda a infra-estrutura documentada através de diagramas, se possível manter um controle de versões onde em cada alteração da sua infra-estrutura tanto de redes quanto dos servidores seja registrada. Acredite, é muito bom você dar uma lida nesses documentos do passado e ver o que você já fez. :-)
  • Em situações de emergência, que ações devem ser tomadas? Isso deve estar devidamente documentado.
  • Fazer guias técnicos que expliquem todos os procedimentos a serem realizados no servidor, como backups, atualizações, gerenciamento de usuário, analise de Logs, etc…

Enfim, tudo que você julgar importante (ou não) documente! Informação nunca é demais! ;-)

Documentação para o usuário:

Nem sempre estamos disponiveis para resolver problemas de usuários então é importante escrevermos guias de como solucionar certos problemas e como realizar certas tarefas básicas, como: Trocar senha, detectar problemas de e-mail, como configurar uma impressora, etc. Isso varia muito de acordo com a política da empresa.

É importante que a documentação esteja escrita em linguagem acessível com screenshots e explicando passo-a-passo como fazer os procedimentos e configurações necessárias na maquina do cliente.

Como fazer a documentação?

Já deu para perceber que documentar é quase que uma tarefa diária, sempre vai aparecer alguma coisa que você vai achar interessante documentar. Então temos que fazer da forma mais simples possível.

Acho que mais de 90% de todas as documentações que eu vejo por ai estão disponíveis ou em formato HTML e PDF. Eu só recomendo o formato PDF se você for disponibilizar o arquivo para download, pois em um único arquivo você estará disponibilizando todos os textos e imagens.

Se você optar em fazer a documentação em HTML, você poderá perder um certo tempo escrevendo as marcações que o html necessita. Existem alguns programas e ferramentas que facilitam (e muito) sua vida.

Hoje em dia vemos muito por aí os Wikis que são ambientes colaborativos para criação de documentos para web. A linguagem de marcação é muito simples, vale a pena tentar.

Outro programa muito utilizado (que inclusive eu uso bastante) é o txt2tags, que faz um trabalho parecido com o wiki. Ele converte uma linguagem de marcação muito simples para html, na verdade já formata vários outros formatos, vale a pena conhecer.

Links relacionados:

1