DOCUMENTAO DE SOFTWARE: UMA NECESSIDADE

COELHO, Hilda Simone1

1

Universidade Federal de Minas Gerais, Faculdade de Letras, MG, Brasil

* e-mail: hildacoelho2003@yahoo.com.br

RESUMO
Este trabalho tem como objetivo mostrar a importncia da documentao em software e apresentar algumas ferramentas
mais comuns bem como trazer os resultados de uma pesquisa com profissionais desenvolvedores de programas de software
sobre as ferramentas mais utilizadas para a documentao.
Palavras-chave: documentao de software; ferramentas de documentao.
ABSTRACT
This work aims to discuss about the importance of software documentation and to show some examples of tools for this
purpose. It also brings the results of a research done with professionals of the area about the most used tools for software
documentation.
Keywords: software documentation; tools for software documentation.

Introduo

manuteno, mas afirmaram que de extrema

dificuldade a redao de uma documentao que
Fazer uma pesquisa sobre ferramentas de facilite o uso e a compreenso do software para o
documentao em software foi um grande desafio. usurio, principalmente se pensar a possibilidade de
Sendo da rea de Lingstica Aplicada, me vi na ser este um leigo nos caminhos da informtica.
obrigao e necessidade de fazer uma busca detalhada
nas bibliotecas com a expectativa de encontrar
Segui minha busca pela internet e encontrei
referencial terico para dar subsdio a este trabalho. disponibilizados alguns trabalhos de colegas de outras
Qual no foi minha surpresa ao encontrar pouco instituies, a maioria material em power point, outros
material, incluindo pesquisas, com foco em pequenos artigos disponibilizados em sites para o
documentao e ferramentas para a documentao de desenvolvimento de documentao de software, e
software.
outros poucos artigos em pdf que discorriam
especificamente sobre o assunto.
Continuei minha busca e parei em uma
empresa de programao de software, especificamente
Desta forma, acredito na relevncia deste
o desenvolvimento de jogos pedaggicosi. Outra trabalho que, alm de compartilhar o sentimento dos
surpresa: os tcnicos deram o depoimento de que, pesquisadores e profissionais da rea sobre a escassez
apesar de saberem da importncia da documentao, de material sobre documentao em software, tem
reconhecem a dificuldade para realiz-la de forma como objetivo discutir a importncia da documentao
adequada e eficiente para o usurio; conseguem de software e trazer a exemplificao de algumas
construir uma documentao que registre os passos da ferramentas bsicas de documentao, como, tambm,
construo do software que venha facilitar sua mostrar os resultados de uma pesquisa sobre as
N.o 2 vol. 1 outono de 2009

http://www.textolivre.net [1]

ferramentas mais utilizadas para documentao.

diferentes tecnologias para tal.

Este trabalho est organizado da seguinte

forma: primeiro apresento a definio de
documentao, a seguir trago exemplos de algumas
ferramentas de documentao e, por ltimo, mostro os
resultados de uma pesquisa sobre as ferramentas mais
utilizadas (SOUZA et al 2004).

Ao explicar sobre o uso da linguagem de

modelagem UMLii, BOOCH, RUMBAUGH e
JACOBSON (2006) afirmam que a documentao, a
modelagem de um software, uma parte central de
todas as atividades que levam implantao de um
bom software. Sua construo deve:

Comunicar
comportamento do sistema;

1. O que documentao?
Documentao descreve cada parte do
cdigo-fonte, uma funo, uma classe, um trecho ou
mdulo. Podemos dizer que a documentao consiste
em um conjunto de manuais gerais e tcnicos, podendo
ser organizado em forma de textos e comentrios,
utilizando ferramentas do tipo dicionrios, diagramas e
fluxogramas, grficos, desenhos, dentre outros.
As empresas de software bem sucedidas
sabem que precisam desenvolver seus produtos
cumprindo prazos, garantindo a qualidade e a
eficincia de seus recursos. O produto final que
garante a satisfao do cliente o mais importante,
mas para alcanar o sucesso de um software devem-se
seguir todos os passos de seu desenvolvimento e isto
inclui o conhecimento de seus usurios, expondo a eles
os requisitos reais do sistema (BOOCH et al
2006:3). A evoluo de um software e seu sistema
operacional devem ser claramente informados,
estabelecendo procedimentos para registrar e resolver
problemas, facilitando sua manuteno posterior e,
assim, garantindo sua durabilidade. Para que isto
acontea preciso desprender um tempo precioso em
documentao, designando as pessoas habilitadas
especificamente para esta tarefa e escolhendo as
ferramentas que possibilitem o enfoque correto de
cada passo a ser documentado.
A documentao deve ser feita ao longo do
desenvolvimento do software. Problemas de custos,
impreciso dos servios fornecidos e dificuldades de
manipulao podem ser causadas pela ausncia de
documentao ou quando esta construda aps o
desenvolvimento do software. A documentao exige
seu planejamento, isto , a identificao dos
documentos, o estabelecimento de sua organizao, a
definio da linguagem a ser utilizada e um estudo das
N.o 2 vol. 1 outono de 2009

sistema;

estrutura

Visualizar e controlar a arquitetura do

Expor oportunidades de simplificao

e reaproveitamento;

Gerenciar riscos.

Os mesmo autores reforam a importncia do

planejamento do software e de sua documentao
comparando sua construo a construo de casas e
prdios. Assim como o projeto arquitetnico e o de
engenharia de um imvel deve guiar os passos da
construo, o segredo de um software bem sucedido
uma questo de arquitetura, processo e ferramentas
(BOOCH et al 2006: 5).
Tendo exposto o que documentao e
tratado de justificar sua importncia, apresentaremos a
seguir os tipos de documentao e algumas
ferramentas mais comuns.

2. Tipos de documentao
Segundo Michelazzo (2006), a documentao
pode ser dividida em dois grandes grupos, conforme a
tabela 1.
A parte tcnica considerada mais simples,
pois descreve o trabalho do desenvolvedor, enquanto
que a parte para o usurio a mais exigente e requer
habilidades especiais para a redao de manuais,
insero de screenshots, desenhos e outros elementos
grficos.

http://www.textolivre.net [2]

DOCUMENTAO
TCNICA

DOCUMENTAO
USO

DE

Voltada ao
desenvolvedor

Compreende
dicionrios e modelos de
dados, fluxogramas de
processos e regras de
negcios, dicionrios de
funes e comentrios de
cdigos

Voltada para o
usurio final e o
administrador do sistema

Formada por
apostilas ou manuais que
apresentam como o manual
deve ser usado, o que esperar
dele e como receber as
informaes que se deseja

3. Ferramentas de documentao
Seguindo a exemplificao de Michelazzo
(2006), apresentaremos alguns tipos de ferramentas de
documentao.
3.1. Documentao de cdigo: feita basicamente de
duas formas comentrios dentro do prprio cdigo e
gerao de documentao online. O desenvolvedor
deve ter a conscincia de que no ser o nico a
colocar a mo no sistema e por isso deve fazer o
comentrio dos cdigos de maneira bastante clara. Um
exemplo de um cdigo 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) {
(fonte: http://www.michelazzo.com.br/node/123)

Michelazzo (2006) ressalta que no o

nmero de linhas de comentrios que garante a
eficcia da documentao, mas a ausncia de
comentrios poder acarretar gastos desnecessrios de
horas de trabalho procura de erros e possivelmente
provocar estresse em todos que iro lidar com o
software.
3.2. Modelos de dados: refletem de forma grfica (e
lgica) a base de dados de um sistema, seus
relacionamentos, entidades, chaves e tudo aquilo que
se refere aos dados em si. , portanto, considerado
pea fundamental para o desenvolvimento de um
sistema e por isso so pensados e criados antes do
incio do desenvolvimento. Podem ser criados por
meio de engenharia reversa ou ainda baseando-se nas
necessidades do aplicativo que est sendo envolvido.
As ferramentas mais conhecidas para a modelagem
dentro do mundo livre so DBDesigner, MySQL
Workbench e PGDesigner, as quais possuem
funcionalidades diferentes e dispem de verses tanto
para Linux quanto para Windows.
3.3. Dicionrios de dados: arquivo ou documento que
define a organizao bsica dos dados do banco. Nele
so informadas as tabelas, os campos, suas definies,
tipos e descries. Um exemplo simples de um
dicionrio de dados pode ser visto a seguir:
Campo

Tipo

Tam.

Proprieda Desc.
des

id_
cadastro

Int

AutoID
do
increment registro do
cadastro

na_nome

Varchar

50

Not Null

Nome do
dono
da
empresa

na_empres Varchar
a

50

Null

Nome da
empresa

ad_email

Varchar

75

Not Null

Endereo
de e-mail
principal

nu_fone

Varchar

14

Not Null

Telefone de
contato

(fonte: http://www.michelazzo.com.br/node/123)
N.o 2 vol. 1 outono de 2009

http://www.textolivre.net [3]

documentao, passaremos a tratar do uso e da

importncia da documentao, apresentando mais
3.4. Fluxogramas: apresentam graficamente a adiante, os resultados de duas pesquisas realizadas
seqncia lgica das informaes de um processo ou para o conhecimento de ferramentas mais relevantes
sistema, utilizando vrios elementos de geometrias no momento da manuteno em software.
diferentes que indicam uma das partes do processo.
Visualmente conseguem passar a lgica de todo um
sistema desde os nveis mais altos de processamento
at pequenas partes, permitindo, assim, uma viso 4. Usos da documentao
geral do que realmente precisa ser feito dentro de um
sistema. Um exemplo de fluxograma pode ser visto a
Segundo AMBLER (2001) h duas razes
seguir:
bsicas para documentar: auxiliar a comunicao
durante o desenvolvimento do software e auxiliar o
entendimento nas atividades de manuteno e
atualizao quando se fizerem necessrias.
Os especialistas em manuteno afirmam que
mais de 50% do trabalho de evoluo de um software
dedicado ao entendimento do programa e a tarefa mais
difcil da manuteno o entendimento da estrutura do
sistema. Por isso, o desenvolvedor deve encontrar um
ponto de equilbrio na quantidade de documentao
gerada e encontrar as ferramentas que facilitaro o
entendimento da documentao, tanto para o
administrador quanto para o futuro usurio do
software.

(fonte: http://www.gliffy.com/pubdoc/1366615/L.jpg)

Alguns problemas so apontados pela falta de

documentao adequada. Dentre eles podemos citar as
dificuldades para a atualizao e manuteno,
dificuldades de acesso do usurio e alto custo para o
software.

Existem algumas ferramentas para criar

Outra questo relevante o cumprimento do
fluxogramas como, por exemplo, DIA e o
prazo de entrega do software, fator essencial para a
OpenModeling, disponveis em vrias plataformas e
sobrevivncia de uma organizao, e que est
livros.
intimamente ligada quantidade e qualidade da
documentao. Alguns mtodos geis vm ganhando
Existem vrias outras ferramentas que
popularidade, como, por exemplo, o Extreme
facilitam a vida do programador na hora de gerar a
Programming (XP).
documentao (vide lista disponvel em Souza et al,
2005). VAILATI (2006), por exemplo, aborda em seu
artigo a utilizao do PHPDocumentor, uma excelente
ferramenta para a linguagem PHP que gera
automaticamente a documentao, baseada em tags 5. Ferramentas mais utilizadas
prprias contidas nos cdigos fonte. O desenvolvedor
No intuito de trazer neste trabalho as
do software deve procurar pelas ferramentas que mais
ferramentas
de documentao mais recorrentes,
o ajudam na descrio de determinada parte do
apresentaremos
os resultados de duas pesquisas
documento.
discutidas por SOUZA, ANQUETIL & OLIVEIRA
Uma vez conhecido algumas ferramentas de (2005). Ambas foram realizadas com profissionais da
N.o 2 vol. 1 outono de 2009

http://www.textolivre.net [4]

rea de desenvolvimento de software, sendo 65%

Souza et al (2005) apontam que outras oito
analistas de sistemas; 25% gerentes; 7% ferramentas foram assinaladas pelos profissionais
programadores e 3% consultores.
entrevistados, mostrando uma recorrncia entre 85,7 %
(manual do usurio, plano de implantao unitrio,
A primeira pesquisa buscou identificar as plano de testes) a 42,9% (plano de testes de
ferramentas de software que auxiliam no entendimento homologao, diagramas de fluxo de dados, diagrama
do sistema na fase de manuteno. A tabela a seguir hierrquico de funes).
mostra estas ferramentas e traz a definio para cada
tipo.
Dentre as 24 ferramentas apresentadas no
questionrio, 14 foram utilizadas pelos mantenedores.
Isto implica a importncia da documentao e tambm
ferramentas que DEFINIO
DA
auxiliam no
FERRAMENTA
a necessidade de se ter claro o propsito para a qual
entendimento dos
ela criada e mantida. Os autores destacam a
sistemas
importncia do cdigo fonte juntamente com seus
comentrios, da o cuidado que preciso ter com a
Requisitos
Referentes s ferramentas lista de
adoo de padres de codificao e de organizao
requisitos e sua descrio na anlise
interna do cdigo.
estruturada, e diagrama de caso de
uso e sua especificao na anlise
orientada a objetos

Modelos de dados Referentes s ferramentas modelo

lgico e fsico de dados na anlise
estruturada, as mesmas ferramentas
associadas ao diagrama de classe
que a base para a definio desses
modelos na anlise orientada a
objetos
Cdigo

Referente ao cdigo fonte e

comentrios no mesmo nas duas
abordagens

Tabela 2.
A segunda pesquisa teve como objetivo
verificar a real utilizao de cada ferramenta no dia a
dia da manuteno. Os dados foram coletados atravs
de dois questionrios respondidos pelos profissionais
da rea. As cinco ferramentas mais utilizadas podem
ser vistas no grfico abaixo:

100

cdigo fonte

90

comentrios

80
70

modelo lgico
dicionrios
modelo fsico

N.o 2 vol. 1 outono de 2009

Souza et al (2005) argumentam que os

resultados destas pesquisas podem ser teis para a
anlise em torno de outras ferramentas de
documentao de software visando buscar o equilbrio
na produo de ferramentas adequadas.

6. Concluso
Os resultados da pesquisa feita para a
realizao deste trabalho indicam a necessidade de
produzir outros materiais sobre documentao em
software bem como divulgar a importncia do
planejamento da documentao, as escolhas de seus
redatores e das ferramentas mais adequadas a cada
passo a ser documentado, servindo como apoio para os
seus desenvolvedores, ou, para apoio de seus usurios.
Embora compreendamos a limitao deste trabalho,
esperamos ter contribudo para o entendimento do uso
e da importncia da documentao de software e de
algumas ferramentas utilizadas para este fim.

REFERNCIAS BIBLIOGRFICAS
AMBLER, S. W. Agile Documentation. 2001-2004,
The Official Agile Modeling (AM) Site, 2001,
Disponvel em: http://www.agilemodeling.com/essays/
AgileDocumentation.htm Acesso em: nov. 2008.

http://www.textolivre.net [5]

BOOCH, G.; RUMBAUGH, J.; JACOBSON, I. UML:

guia do usurio. Rio de Janeiro: Elsevier, 2005 2
reimpresso, 2006.
MICHELAZZO, P. A Documentao de software,
2006. Disponvel em: http://www.michelazzo.com.br/
node/123. Acesso em: nov, 2008.

oes/pbqp04.pdf. Acesso em: Nov, 2008.

VAILATI, A. T. Documentao de Software , 2006,
disponvel
em:
HTTP://imasters.uol.com.br/artigo/4923/des_de_softw
are/documentacao_de_software. Acesso em nov. 2008.

SOUZA, S. C. B. de; NEVES, W. C. G. das;

ANQUETIL, N.; OLIVEIRA, K. M. de.
Documentao Essencial para a Manuteno de
Software, 2005. Disponvel em:
http://www.web.br/prg/professores/anqueteil/Publicac

N.o 2 vol. 1 outono de 2009

http://www.textolivre.net [6]

Meus agradecimentos aos profissionais Pblisson, Hber, Igor e Henrique, da Jungle Digital Games, que muito me
auxiliaram neste trabalho.
ii Unified Modeling Language, desenvolvida por Grady Booch, James Rumbaugh e Ivar Jacobson por volta do ano de
1996.