DOCUMENTAO DE SOFTWARE: UMA NECESSIDADE COELHO, Hilda Simone1

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.

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]

Introduo

ferramentas mais utilizadas para documentao. 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).

diferentes tecnologias para tal. 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; a estrutura e o

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;

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 Voltada ao desenvolvedor Compreende dicionrios e modelos de dados, fluxogramas de processos e regras de negcios, dicionrios de funes e comentrios de cdigos

DOCUMENTAO USO

DE

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

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 AutoID do increment registro do cadastro Not Null Nome do dono da empresa Nome da empresa Endereo de e-mail principal Telefone de contato

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)

id_ cadastro

Int

na_nome

Varchar

50

na_empres Varchar a ad_email Varchar

50

Null

75

Not Null

nu_fone

Varchar

14

Not Null

(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. 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.

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

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

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.

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 90 80 70

cdigo fonte comentrios modelo lgico dicionrios modelo fsico

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.

N.o 2 vol. 1 outono de 2009

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. 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

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.

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.