| Autor |
Mensagem |
Jiuvaskala
Veterano |
# jan/08 · Editado por: Jiuvaskala
Bom gente, eu entrei num estágio agora e preciso documentar os softares desenvolvidos na empresa. Mas o problema é que não tenho experiência e nunca fiz nenhuma documentação antes. Procurei algo sobre o assunto no Google, mas nada aprofundado.
Por favor, não desvirtuem.
Para quem nao conhece, segue um texto sobre o assunto:
A documentação de software
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 (http://www.fabforce.net), MySQL Workbench (http://www.mysql.com) e também o PGDesigner (http://pgdesigner.sourceforge.net), 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:
Tabela: CadastroCliente
Campo Tipo Tamanho Propriedades Descrição
id_cadastro Smallint 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 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:
Para criar fluxogramas, as mais conhecidas ferramentas são: DIA (http://www.gnome.org/projects/dia) e o OpenModeling (http://www.openmodeling.info), 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 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 desenvolvedor a compreender o que é aquele "monstro" nascido de suas mãos.
Mas isto é assunto para a próxima parte do artigo. Até lá, veja o que é possível ser feito neste sentido: http://clientes.fabricalivre.com.br/doc_sample.
Abraços!
|
izzystradlin
Veterano |
# jan/08
· votar
nossa, é meio longo, mas...resumindo..
você fala em documentação no sentido de registrar a venda, direitos e os manuais etc etc?
|
izzystradlin
Veterano |
# jan/08
· votar
pelo que entendi a parte técnica você não fará correto?
|
Jiuvaskala
Veterano |
# jan/08
· votar
izzystradlin
hmmm....não é bem por aí....
A empresa possui um software de automação para postos de combustíveis....em todo o Brasil...o programa é grande e cheio de detalhes, pelo o que eu entendi, fazendo a pesquisa, preciso fazer duas documentacoes: a técnica e a de suporte para o usuário, ou seja, uma explicando as funções do programa em si(código) utilizando diagramas (talvez UML, nao sei) e outra, voltada para o usuario, como um manual Help...
mas, nao faço idéia de como montar isso..
O.o
|
Jiuvaskala
Veterano |
# jan/08
· votar
e aliás, eu nao sou muito boa para explicar as coisas escrevendo como pode ver....ahuauahauhua
ai ai
|
184486
Veterano |
# jan/08
· votar
Fiquei com preguiça de ler
|
izzystradlin
Veterano |
# jan/08
· votar
Jiuvaskala
hummm..hehe mas eu entendi sim..deixa eu ver...
a parte técnica, você vai ter que manjar um pouco de programação sim, não vai dar pra escapar, isso pq como escreveu ali em cima, tem softwares que te auxiliam, mas algumas coisas você vai ter que ir aprendendo com o tempo, tipo decorando alguns trechos de código e talz....acho que vai depender muito da vontade dos caras em te ensinar ou não, pq é meio complexo pra uma pessoa leiga...enfim
já a documentação de suporte é mais fácil, o manual do programa e como usar etc etc etc, a parte de registrar, direitos autorais, o que o usuário pode ou não fazer, quanto tempo ele pode usar, se der problema como fica a assistência e talz..enfim a parte burocrática...
|
izzystradlin
Veterano |
# jan/08
· votar
a parte dos fluxogramas acho que se o "analista" dos sistemas não te disser tim tim por tim tim vai ser complicado..
ehehhe
|
izzystradlin
Veterano |
# jan/08
· votar
outra coisa que lendo melhor agora eu fui ver...
isso que você pesquisou no google é a parte COMPLETA da documentação e acredito que você ficará com alguma parte em específico, até pq tem coisas ali que só o cara que fez o banco de dados pode te dizer...ehehehe
ex.:
Campo Tipo Tamanho Propriedades Descrição
id_cadastro Smallint 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 Null Telefone de contato
essa parte de criação do banco já te darão pronta com certeza...
|
Jiuvaskala
Veterano |
# jan/08
· votar
izzystradlin
hummm..hehe mas eu entendi sim..deixa eu ver...
a parte técnica, você vai ter que manjar um pouco de programação sim, não vai dar pra escapar, isso pq como escreveu ali em cima, tem softwares que te auxiliam, mas algumas coisas você vai ter que ir aprendendo com o tempo, tipo decorando alguns trechos de código e talz....acho que vai depender muito da vontade dos caras em te ensinar ou não, pq é meio complexo pra uma pessoa leiga...enfim
sim...e não sei se terei uma pessoa só para me explicar...=/
já a documentação de suporte é mais fácil, o manual do programa e como usar etc etc etc, a parte de registrar, direitos autorais, o que o usuário pode ou não fazer, quanto tempo ele pode usar, se der problema como fica a assistência e talz..enfim a parte burocrática...
a parte chata, mas que eu aprendendo a usar o programa e tal, dá pra aprender na boa...
a parte dos fluxogramas acho que se o "analista" dos sistemas não te disser tim tim por tim tim vai ser complicado..
ehehhe
putz....to ferrada!
Comecei na quinta passada, mas acho q essa semana já vao cobrar pra q eu comece a escrever algo...
vamos ver..valeu pelas dicas!!
|
Jiuvaskala
Veterano |
# jan/08
· votar
izzystradlin
essa parte de criação do banco já te darão pronta com certeza...
que bom! pelo menos uma boa notícia! to começando a aprender agora....dá medo! hauahuah
|
izzystradlin
Veterano |
# jan/08
· votar
Jiuvaskala
uheauhaehu..kpz..no stress..
lembre-se, vc é só estagiária, eles não vão te cobrar antes de dar uma boa noção do que fazer.....aliás cê tá ali pra aprender muita coisa tbm ehehe..
pensa positivo e mete a cara pra bater..hehe
|
Jiuvaskala
Veterano |
# jan/08
· votar
izzystradlin
uheauhaehu..kpz..no stress..
lembre-se, vc é só estagiária, eles não vão te cobrar antes de dar uma boa noção do que fazer.....aliás cê tá ali pra aprender muita coisa tbm ehehe..
pensa positivo e mete a cara pra bater..hehe
=)
acho que agora eu vou conseguir dormir man! hauahauha
eu nao quero dar bola fora...ehehe
mais detalhes na próxima edição!!!
Fui!
|
kiki
Moderador |
# jan/08
· votar
vou ensinar... tem um comando que chama printscreen
|
Gan
Veterano |
# jan/08
· votar
Pelo q eu entendi vc vai ter q fazer o trabalho dos desenvolvedores vagabundos q não comentaram o código, essa é a parte mais complicada.... vc vai ter q entender o código comentar, montar os malditos diagramas ,enfim. Q coisa estranha uma emrpesa fazer isso depois q o programa está pronto, isso é coisa de amador... de aluno q documenta só pra mostrar pro professor...
Quanto a documentar para o usuário, é simples certo?
abraços
|
_FrEd_
Veterano |
# jan/08
· votar
Qnd sair o DVD da um up!
po, complicado demais, pergunta pra Sam que ele deve saber
|
CheshireCat
Veterano |
# jan/08
· votar
Gan
Q coisa estranha uma emrpesa fazer isso depois q o programa está pronto, isso é coisa de amador... de aluno q documenta só pra mostrar pro professor...
po, mas lá na nossa empresa eu fiz toda a documentação do projeto depois dele estar sendo desenvolvido há anos ¬¬
Jiuvaskala
a documentação varia de empresa pra empresa... tenta procurar exemplos de como as pessoas costumam fazer isso e segue o padrão...
pra fazer "manual do usuário", é simples... comenta passo a passo o que tem que fazer como se o usuário fosse uma ameba, coloca screenshots e fica bunitinho =) mas veja se tem padrão também...
|
TG Aoshi
Veterano |
# jan/08
· votar
Jiuvaskala
Desculpa, mas tô meio (...totalmente...) sem tempo aqui, então nem li o que vc postou...
Já que comentaram de "seguir o 'padrão'", já tentou dar uma olhada pra ver se não tem nada da ABNT sobre isso?
Se tiver, não vai resolver seu problema, mas talvez ajude bastante!
|
russobass
Veterano |
# jan/08
· votar
Jiuvaskala
puxa eu fiz documentação de software.
você precisa procurar engenharia de software, e procura a parte de documentação
se vc me passar seu email, eu mando a minha documentação
manda um email para mim russopp@itelefonica.com.br
que eu mando de volta um material de documentação explicado cada item.
mas vc tem que analisar bem o software que vc vai documentar.
pois se o software for orientado a objeto a documentação muda um pouco.
fui...
|
Jiuvaskala
Veterano |
# jan/08
· votar
russobass
mandei um email pra ti!!
|
Jiuvaskala
Veterano |
# jan/08
· votar
CheshireCat
Gan
muito obrigada pelas dicas de vcs...se tiverem algum material q possam me passar a respeito do assunto...=)
=*****
|
Jiuvaskala
Veterano |
# jan/08
· votar
TG Aoshi
Já que comentaram de "seguir o 'padrão'", já tentou dar uma olhada pra ver se não tem nada da ABNT sobre isso?
ainda nao!! mas eu vou dar uma pesquisada....=)
valeu pela dica!
|
gsprs
Veterano |
# jan/08
· votar
preciso fazer duas documentacoes: a técnica e a de suporte para o usuário, ou seja, uma explicando as funções do programa em si(código) utilizando diagramas (talvez UML, nao sei) e outra, voltada para o usuario, como um manual Help...
Exatamente.
|
gsprs
Veterano |
# jan/08
· votar
Jiuvaskala
Só uma coisa.
Isso é chato pra caralho. Tenho pena de você. =/
|
stenyosullivan
Veterano |
# jan/08
· votar
Jiuvaskala
particularmente pramim, documentaçao de um software é vc descrever, ou detalhar o algoritmo num todo, o que cada funçao faz, descrever as variaveis e pra que vc ira usar elas e talz, pramim isso é feito para que se outro programador for pegar o seu codigo para terminar ou fazer algum tipo de manutençao, ficara mais facil pra ele entender o seu codigo, sendo assim agiliza o desenvolvimento do software ;), quando eu faço alguns softwares meio grandes, quando eu tenho tempo, eu documento umas partes mais dificeis, para que futuramente, se eu precisar de fazer algo com o codigo, ficara mais facil pra entender =).
|
128556
Veterano |
# jan/08
· votar
stenyosullivan
pode ser para nao copiarem seu programa tambem ?
|
stenyosullivan
Veterano |
# jan/08
· votar
ah, e tem o esquema de normas padronizadas, sobre isso ae eu estou por fora, tenta fazer do seu jeito, ou qualquer coisa, poste o seu codigo, de repende a moçada do OT da um jeito de documentar =)
|
stenyosullivan
Veterano |
# jan/08
· votar
128556
sobre a copia de programa, no caso vc teria que registrar o seu algoritmo num cartorio ou algo assim, eu sei que tem que ser feito algo assim.... pq eu acho que isso entra como direitos autorais.....
|
Jiuvaskala
Veterano |
# jan/08
· votar
stenyosullivan
quando eu faço alguns softwares meio grandes, quando eu tenho tempo, eu documento umas partes mais dificeis, para que futuramente, se eu precisar de fazer algo com o codigo, ficara mais facil pra entender =).
vc faz a coisa certa man!!!
no meu trabalho ningum faz isso..e to entrando agora,, valeu pelas dicas
ah, e eu nao sei programar ainda
|
maggie
Veterana |
# jan/08
· votar
Jiuvaskala
Bom gente, eu entrei num estágio agora e preciso documentar os softares desenvolvidos na empresa. Mas o problema é que não tenho experiência e nunca fiz nenhuma documentação antes. Procurei algo sobre o assunto no Google, mas nada aprofundado.
Se eu captei a vossa mensagem, o que tu precisa é o seguinte:
• Documentar o softs desenvolvidos, ou seja, guardar (física e/ou digitalmente) os projetos desenvolvidos, junto com uma "capa" contendo breve descrição do que é, o que faz, quando foi feito, para quem foi vendido etc.
• Esses softs devem ser vendidos protegidos, então se for no varejo deve ter contrato específico para cada cliente, ou para vários clientes, restringindo alterações no código-fonte. Essa documentação tu guarda junto.
Se for um trabalho de arquivamento e organização, é isso.
Agora, se for programação, pede pro izzystradlin.
Se o programa é padrão pra todos clientes, é mais fácil desenvolver um manual. Nesse caso, te recomendo desenvolver um bem detalhado e outro para consultas rápidas.
|