Dicas para documentação de softwares

Necessidade ou preciosismo? A documentação de software mesmo sendo o carma de qualquer desenvolvedor, é extremanente necessária e auxilia na redução de horas preciosas na correção de problemas. Neste primeiro momento, vamos ver o que é a documentação de um sistema, suas partes principais e também as ferramentas que auxiliam desenvolvedores a fazer desta uma tarefa menos maçante.

Para muitos desenvolvedores a criação de documentação técnica é a parte mais aterrorizante para se enfrentar em todo o processo de criação de um software, seja pela necessidade de escrever várias e várias páginas de texto, gráficos e desenhos ou ainda pela necessidade de largar aquilo que se aprendeu (programar) para fazer aquilo que não sabe bem (redigir).

Entretanto a documentação é parte integrante de qualquer sistema ou programa criado. Arrisco a dizer inclusive que a documentação é tão importante (ou mais) que as questões de segurança pois sem a devida documentação, bug’s e pontos vulneráveis no sistema demoram a ser encontrados e corrigidos, permitindo assim que os ataques continuem levando à falência múltipla do sistema e, consequentemente, de seu usuário.

Normalmente em grandes corporações existem pessoas e/ou equipes voltadas única e exclusivamente para a criação de documentação, sendo que o desenvolvedor fica restrito à codificação e comentários de seu código. Já no mundo “real”, esta atividade é realizada pelo próprio desenvolvedor e demanda um bom conjunto de horas para planejar e criar cada uma de suas partes a fim de atender minimamente as necessidades do produto desenvolvido. Então, como não é possível evitar a criação da documentação técnica, vamos tentar amenizar um pouco sua horrível aparência usando ferramentas que auxiliam na tarefa de domar o monstro. Mas antes disso, uma pequena apresentação do que é a documentação em si.

Documentação, o que é?

A documentação de um software é composta por várias partes diferentes que abrangem todo o sistema e pode ser dividida em dois grandes grupos: documentação técnica e documentação de uso. A primeira é voltada ao desenvolvedor ou pessoa de TI e compreende principalmente dicionários e modelos de dados, fluxogramas de processos e regras de negócios, dicionários de funções e comentários de código. Já a documentação de uso é voltada tanto para o usuário final quanto para o administrador do sistema e comumente é formada por apostilas ou manuais que apresentam como o software deve ser usado, o que esperar dele e como receber as informações que se deseja.

A primeira parte (técnica) é, para o desenvolvedor, a mais simples pois literalmente descreve seu trabalho e também é utilizada pelo mesmo como ferramenta para o desenvolvimento de um bom código. Já a segunda costuma ser um martírio pois a redação de manuais, inserção de screenshots, desenhos e outros elementos gráficos não é aquilo que podemos considerar como skill deste profissional (são raros os que possuem).

Ambas podem ser criadas em vários formatos de visualização tais como páginas HTML, documentos PDF, apresentações, vídeos ou ainda arquivos texto. A forma de apresentação não importa. O importante é saber que para cada tarefa existe uma ferramenta certa, inclusive para a documentação de sistemas em qualquer nível de complexidade ou necessidade e que precisa ser feita, de uma forma ou de outra.

As ferramentas para documentação

Aproveitando a divisão da documentação em duas grandes áreas, vamos conhecer suas partes e algumas ferramentas que ajudam e/ou facilitam aqueles que tem pela frente a tarefa de gerar documentação de sistemas.

Modelos de dados
Modelos de dados são aquelas folhas com várias caixinhas das tabelas de um banco de dados interligadas e que muitas vezes somente são utilizadas para decoração de escritórios. Mas longe de ser um quadro ou pôster, o modelo de dados reflete de uma forma gráfica (e lógica) a base de dados de um sistema, seus relacionamentos, entidades, chaves e tudo aquilo que é referente aos dados em si.

Este modelo, junto com o dicionário de dados, é peça fundamental para o desenvolvimento de um sistema, sendo inclusive pensado e criado ANTES do início do desenvolvimento. Um bom modelo de dados bem pensado e bem estruturado não impacta somente em um bom código, mas também na performace da aplicação com um todo e na redução de horas de desenvolvimento equivocado.

Para criá-lo são utilizadas ferramentas de modelagem de dados, as quais geram de forma gráfica as tabelas, índices, relacionamentos e tudo aquilo que tem a ver com a base de dados em si, podendo ser criados por meio de engenharia reversa ou ainda baseando-se nas necessidades do aplicativo que está sendo desenvolvido.

As ferramentas mais conhecidas para modelagem de dados dentro do mundo livre são o DBDesigner, MySQL Workbench e também o PGDesigner, as quais possuem funcionalidades diferentes e dispõem de versões tanto para Linux quanto para Windows.

Dicionário de dados
Como o próprio nome sugere, o dicionário de dados nada mais é que um arquivo ou documento que define a organização básica dos dados do banco. Nele são informadas as tabelas, os campos, suas definições, tipos e descrições (para que serve este campo?). Um exemplo simples de um dicionário de dados pode ser visto a seguir:

Campo Tipo Tamanho Propriedades Descrição
id_cadastro Int 5 Auto-increment ID do registro do cadastro
na_nome Varchar 50 Not Null Nome do dono da empresa
na_empresa Varchar 50 Null Nome da empresa
ad_email Varchar 75 Not Null Endereço de e-mail principal
nu_fone Varchar 14 Not Null Telefone de contato

Com um arquivo destes, mesmo simplório em conjunto com o modelo de dados, a possibilidade de erro na hora do desenvolvimento fica extremanente reduzida quando falamos de acesso à dados na base, além de economizar neurônios que muitas vezes estão sendo usados para armazenar a informação que o campo varCodSysFil01 é o código de uma filial.

Fluxogramas
Tão antigos quanto a computação, os fluxogramas apresentam graficamente a sequência lógica das informações de um processo ou sistema, utilizando para isso vários elementos de geometrias diferentes que indicam cada uma das partes do processo. Sua importância, mesmo deixada de lado, é grande pois a partir dele (e conjuntamente com o modelo e dicionário de dados), inicia-se o projeto de um sistema eficiente e bem desenvolvido.

Da mesma forma que o modelo de dados, fluxogramas são muitas vezes (mas não deveriam) utilizados como pôsters de escritório. Eles são mais que isso: visualmente conseguem passar a lógica de todo um sistema desde os níveis mais altos de processamento até pequenas partes, permitindo assim uma visão geral do que realmente precisa ser feito dentro do sistema.

Um exemplo de um fluxograma pode ser visto a seguir:

Fluxo de documentação

Para criar fluxogramas, as mais conhecidas ferramentas são: DIA e o OpenModeling, ambas disponíveis em várias plataformas e livres.

Documentação de código

Para muitos, a parte mais chata. Para outros, a mais importante. A documentação de código é feita basicamente de duas formas: comentários dentro do próprio código e geração de documentação online (ou física).

No primeiro caso normalmente o desenvolvedor acredita que sua memória nunca irá falhar e que somente ele irá colocar a mão no sistema, deixando de documentá-lo e gerando problemas gigantescos para sí e para outros profissionais. Um conjunto de cometários bem feito é tão importante quanto uma lógica bem estudada. Funções, constantes, inclusão de arquivos, campos de tabelas e outros elementos sempre proliferam de forma exponencial dentro do sistema, o que leva na maioria das vezes o desenvolvedor a simplesmente criar novos “remendos” com constantes “adicionais” ou variáveis novas, pois não se recorda onde está aquela função que formata determinado campo (quem não passou por isso?).

Um pequeno exemplo de um código bem comentado pode ser visto a seguir:

$database->setQuery( $query );
$rows = $database->loadObjectList();

// establish the hierarchy of the menu
$children = array();
// first pass – collect children
if ($rows) foreach ($rows as $v ) {
$pt = $v->parent;
$list = @$children[$pt] ? $children[$pt] : array();
array_push( $list, $v );
$children[$pt] = $list;
}
// second pass – get an indent list of the items
$list = mosTreeRecurse( 0, ”, array(), $children, max( 0, $levellimit-1 ) );
// eventually only pick out the searched items.
if ($search) {

Observe que não são necessárias dezenas de linhas de comentários para compreender o que determinada área do sistema executa. Mas se estas simples linhas forem deixandas de lado, além de gerar um gasto desnecessário de horas à procura de erros, aumenta-se o nível de estresse de todos que irão mexer no código e principalmente de quem paga por ele.

Para a criação de documentação de código online são utilizadas ferramentas que, baseadas nos comentários existentes dentro do código, permitem a geração de documentos que efetivamente explanam o sistema de forma macro, relacionando arquivos que são incluídos em outros, funções, seus parâmetros e retornos, constantes e uma infinidade de informações que auxiliam qualquer desenvovedor a compreender o que é aquele “monstro” nascido de suas mãos.

Mas isto é assunto para a próxima parte do artigo.

14 Comentários

  1. Michelazzo, quero parabenizá-lo pela exoplicação clara e objetiva da importância de se documentar e saber como fazê-lo.
    Gostaria de pedir que se possível explane um pouco mais osbre o assunto, e acrescente ainda os dois tópicos faltantes (Geração de documentação online e Geração de documentação física) no subtítulo Documentação do código.

    No aguardo

    Responder
  2. Excelente. Estou começando agora com banco de dados e me pediram para fazer uma documentação de modelos de nomenclatura, é de fato massante mas importantíssimo!

    Responder
  3. Olá! Parabéns pela exlpicação!
    Sou técnica em documentação e gostaria de saber se há algum software free para criar documentação e gerá-la em PDF e HTML. Hoje, utilizo o Help & Manual, mas sua interface é ultrapassada e não me agrada. Caso conheça algum similar, por favor, informe. Grata!

    Responder
    • Vanessa,

      O LibreOffice faz isso. Não seria o que procura?

      Responder
      • Obrigada pela resposta rápida, mas infelizmente o produto não atendeu as expectativas. Encontrei o programa HelpNDoc, bastante parecido com o Help & Manual. Seu único problema é que na versão free aparece no rodapé uma mensagem automática que não consigo retirar. Mesmo assim, muito obrigada pela ajuda.

        Responder
  4. Olá Paulino! Achei super interessante e bem escrito o texto acima!Me ajudou em um trabalho da faculdade!! Faço faculdade de Análise e Desenvolvimento de Sistemas e pretendo seguir a carreira como analista. Gostaria de saber as suas dicas e experiência (e de outros profissionais também) para me ajudar, já que estou no começo da trajetória. Seria importante para mim. Agradeço desde já quem puder me ajudar.

    Contato: jcp_julianapereira@yahoo.com

    Responder
  5. Muito bom. Paulino eu preciso documenta um sistema de gestao desenvolvido sem minima documentacao, o sistema esta rodando aparentemente perfeitamente,nao fui eu que originalmente desenvolveu o sistema e nao ha ninguem na equipe que tenha participado desde a origem.
    Tem alguma idei de como comeco a documentar?
    Tem exemplos de plano de documentacao de sistemas desenvolvidos sem documentacao minima?

    Qualquer ajuda,
    obrigado

    Responder
    • Eu tenho este mesmo problema. Estou numa empresa que usa um CRM feito em VBA, gerenciado pelo MS Access. Preciso fazer documentação dele em três fases. Fase 1: Detalhar toda funcionalidade. Fase 2: Captar novas idéias com gestores de cada área na empresa (Financeiro, Comercial, etc…) para aplicar correções e novas tenologias de gerenciamento. Fase 3: Desenvolver o CRM, partindo do que já existe, porém com intuito de deixá-lo na Web. Será feito em PHP+MySQL.

      Alguém se habilita em dar sugestões?
      Qual software usar para documentar e como iniciar este trabalho.

      Um abraçooo!!!!
      GMachado

      Responder
      • Use um Wiki!

        Responder
  6. Eu li isso lá no iMaster, mas está bom.

    Responder
    • Paulino é colunista do iMasters também!

      Responder
  7. Ótimo texto!
    Se todos os profissionais fizessem isso, seria ótimo!

    Responder
  8. obrigado foi de grande ajuda.

    Responder

Trackbacks/Pingbacks

  1. O poder da documentação do código-fonte - [...] – acessado em 5 de maio de 2013 http://www.michelazzo.com.br/textos/dicas-para-documentacao-de-softwares – acessado em 5 de maio de 2013 [...]

Enviar um Comentário

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

2 × três =