Documentação de Software


Você tem um software quase pronto para ser lançado, mas ainda falta sua documentação e não sabe como inicia-lo? Não se preocupe você não é o único.  Ela é algo deixado para depois pela maioria dos profissionais de TI tanto em pequenas empresas como algumas companhias de grande porte. Mas fique tranquilo, você está na página certa.
No processo de desenvolvimento de um software vamos criando anotações de forma formal ou informal. E todas essas anotações têm características de documentação. Então a questão não é exatamente o que é documentação, mas sim “o que deve ser selecionado como documentação?”. È ai que começamos a parte funcional da coisa...

Por que precisamos de uma documentação? Qual o seu uso?
·         
          - Meio de comunicação entre os membros de  um grupo de desenvolvimento; 
·         - Informações para as pessoas que venham a fazer manutenção no sistema; 
·         - Informações à gerência de modo a ajudar a planejar, fazer o orçamento e o cronograma; 
·         - Informações para ensinar aos usuários como  utilizar e administrar o sistema
·         - Informar aos usuários sobre os termos de uso e política de privacidade.

Como podemos ver a documentação é muito importante para qualquer software e produto que esteja sendo vendido.

E quais são os tipos de documentação?
De forma geral são dois, o do processo (técnica) e o do produto (documentação de uso).

Documentação do processo  
É produzida para que o processo de desenvolvimento do software seja administrável. Registram os processos de desenvolvimento e manutenção do software.

Documentação do produto  
Descreve o software que está sendo desenvolvido. É muito utilizada depois que o sistema é implementado, mas é essencial também para a  administração do processo de desenvolvimento.

Sobre Documentação de Processo (Técnica)
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 têm 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 performance 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 si e para outros profissionais. Um conjunto de comentá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 deixadas 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 desenvolvedor a compreender o que é aquele “monstro” nascido de suas mãos.
Sobre Documentação do Produto (Documentação de Uso)
Agora o mais temido a documentação do produto. Ela é 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.

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 ou por um analista ou técnico de documentação de software (mas muitas vezes não há este profissional na empresa) 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.
Sobre o Meus Serviços
Como apresentado sobre documentação de processo e de produto; ofereço um serviço diferenciado de análise de documentação do seu software. Mais especificadamente no desenvolvimento dos termos de uso. Como:
Manuais: Para o usuário final, administradores de sistemas e pessoal de apoio;
Licença: Informar as ações autorizadas ou proibidas, os direitos do autor e as leis que o protege. Neste caso para softwares proprietários.
Política de privacidade: Informar ao usuário sobre a ética que o desenvolvedor tem para com o seu cliente.
Apresentação ou descrição: Fazer um texto explicando a que categoria o software pertence e um breve texto sobre suas funcionalidades.


Clique aqui para contatar-me sobre os meus serviços e consultoria em documentação de software. Certamente irei ajudá-lo da melhor forma possível.





0 comments:

Post a Comment