Utilize uma ferramenta Wiki para criar a documentação necessária

Organizar ou criar uma documentação é uma necessidade de todo ser humano. Quando existe uma padronização é ainda melhor. Atualmente uma forma de documentação muito utilizada baseia-se no método Wiki, que é uma abreviação de WikiWiki que significa Super Rápido.

O método Wiki, é assim que irei chamá-lo, nada mais é que um “software colaborativo que permite a edição coletiva dos documentos usando um sistema que não necessita que o conteúdo tenha que ser revisto antes da sua publicação”.

Com a utilização de um software para essa finalidade ganha-se tempo na edição/revisão de documentos. Além disso a sua principal vantagem é que as ferramentas wiki existentes são voltadas à WEB, ou seja, para poder utilizá-las basta apenas um Web Browser. Dessa forma qualquer pessoa, que tiver acesso à um Browser pode colaborar com a edição/revisão de documentos.

Uma outra vantagem que vale a pena ressaltar é que as ferramentas Wiki, possuem um histórico de tudo o que é alterado, com isso é possível consultar o que foi alterado de uma versão antiga para uma versão nova de um determinado documento.

O software mais famoso para ser utilizado como wiki é o mediawiki, que é o software oficial do portal mais famoso: Wikipédia. Logo da Wikipedia

A wikipédia é sem dúvida nenhuma o maior acervo “enciclopédico” mundial. Só para se ter uma idéia enquanto esse documento é escrito a wikipédia possui mais de 2.331.000 artigos em ingês e mais de 371.000 artigos em português.

Uma outra grande vantagem do uso de um software wiki é a facilidade que se tem para linkar os documentos. Por exemplo: imagine que você está escrevendo um documento sobre dinossauros. No decorrer do documento, provavelmente você citará nomes de algumas espécies de dinossauros, como o exemplo abaixo:

  Os dinossauros (do grego "deinos"(´terrível) e "saurus"(réptil)) constituem uma
superordem de membros de um grupo de arcossauros referente ao final do período
Triássico (cerca de 225 milhões de anos atrás) e dominante da fauna terrestre
durante boa parte da era Mesozóica, do início do Jurássico até o final do período
Cretácico (cerca de 65 milhões de anos)...
...
...
...
Algumas espécies de dinossauros bastante conhecidas são:      * Alossauro
* Arqueopterix
* Braquiossauro
* Carnotauro
* Ceratossauro
* Diplódoco
* Espinossauro
* Estegossauro
* Hadrossauro
* Herrerassauro
* Hipsilofodonte
* Iguanodonte
* Megalossauro
* Ornitomimo
* Oviráptor
* Protocerátopo
* Sacissauro
* Tiranossauro
* Tricerátopo
* Troodonte
* Velociráptor

Imagine você lendo o texto acima, no final do texto existe uma relação de expécies, onde existe um hiperlink para a página, onde existe a documentação para cada espécie. Em outras palavras existe uma super facilidade para o leitor, pois com apenas um clique pode ser direcionado para uma outra página contendo outras informações.

Essa facilidade descrita acima pode ser empregada para qualquer área! Como o meu ramo de atuação é tecnologia conheço muitos softwares onde toda a documentação do software é feita através de uma ferramenta wiki.

Criando uma documentação eletrônica e com uma ferramenta wiki podemos estabelecer acesso às informações de maneira mais prática e confiável.

Para documentar sistemas ou ambientes tecnológicos, a primeira coisa que precisamos é decidir qual ferramenta utilizar, atualmente existem várias ferramentas para essa finalidade.

Ferramenta escolhida é chegada a hora de começar a documentar!

Uma ferramenta Wiki possui uma página “PAI”, e sub-páginas. Dessa forma é possível criar toda a base de documentos necessária.

Vou demonstrar um exemplo que utilizo há um bom tempo!

Na página inicial, sempre explico o que é a ferramenta e já crio as primeiras “seções” que serão utilizadas para criar toda a documentação. Vejamos como seria o seu funcionamento.

Essa área é de exclusividade do departamento XZY, que é o responsável por prover os seguintes serviços para a empresa. Além dos serviços, acima o departamento XYZ, também realiza o gerenciamento dos servidores e da rede interna. Todos esses serviços são realizados pela equipe que é conhecida como Equipe de Suporte que é dividida internamente em Infra-estrutura e HelpDesk.

Nesse pequeno texto, que é a página inicial (“PAI”), do Wiki faço diversos links para às sub-páginas (ou páginas filhas):

  1. XYZ -> vai para apágina do departamento;
  2. serviços -> descreve os serviços que são de responsabilidade do departamento XYZ;
  3. empresa -> aqui pode ser um link para o site oficial da empresa ou para uma página específica, como a Intranet ou uma página dentro do Wiki;
  4. gerenciamento -> nesse link são demonstrados alguns exemplos dos serviços prestados;
  5. servidores -> nessa página é exibida uma lista com os servidores, e cada servidor irá possuir uma página que deve ser criada a partir dessa;
  6. rede interna -> essa página possui informações sobre como é a estrutura da rede, é interessante que nessa página possua um gráfico de rede para uma melhor ilustração;
  7. Equipe de Suporte -> página que contêm informações sobre a equipe de suporte;
  8. Infra-estrutura -> define os serviços que são exclusivos da equipe de infra-estrutura;
  9. HelpDesk -> define os serviços que são exclusivos da equipe de HelpDesk.

Uma fato que deve ser levando em conta é quem irá ser o leitor do conteúdo. Se for apenas a própria equipe alguns assuntos podem ser omitidos, porém se o acesso for mais abrangente, pode ser necessário um amior detalhamento, como por exemplo: você está criando a documentação sobre um servidor específico, assim como os serviços que esse servidor fornecerá, provavelmente você irá escrever as suas principais informações, como por exemplo Sistema Operacional, Capacidade de disco rígido, tipo de RAID utilizado etc…etc.

Para o exemplo acima, vejo que será necessário criar as seguintes páginas:

  • Sistema Operacional;
  • RAID.

Isso é necessário por que o público avo pode não ter conhecimento do que é um Sistema Operacional ou um RAID. E o WIKI deve ser utilizado para facilitar o entendimento de um conteúdo.

A imagem abaixo exemplifica como fica a estrutura de um Wiki:

Mapa Wiki

3 pensamentos em “Utilize uma ferramenta Wiki para criar a documentação necessária”

  1. Uia, não sabia que era um cara que escrevia em blog assim Russo.
    Curti, vou add em casa seu acervo.

    Foguinho. 😉

  2. Bruno, fantastico seu artigo, agora já sei por onde vou começar a minha documentação.
    Sua EAP foi impresindivel para elucidação.
    Parabéns.
    abs

Deixe uma resposta

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *