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.
É 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.
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.
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).
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();
$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) {
$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:
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