Documentação em GNU/Linux

Quando desenvolvemos um software, pensamos obrigatoriamente em equipa-lo de documentação para que nada falte ao utilizador ou até mesmo a nós, programadores, em actualizações futuras.

Apesar de em GNU/Linux não termos importantes e conhecidas ferramentas de criação de documentação como o RoboHelp, WebWorks Publisher ou o FrameMaker, este ambiente é cada vez mais utilizado por escritores de material técnico. De seguida serão apresentadas algumas das mais importantes e mais utilizadas ferramentas de criação de documentação para GNU/Linux.

DocBook XML

O DocBook Project não é uma aplicação, mas é incondicionalmente a melhor ferramenta no que toca a criação de documentação em Linux. É uma variante de XML desenhada para criar manuais de software e hardware, dependendo do que queremos fazer. Com o DocBook podemos criar documentação em diferentes formatos, incluíndo PDF e PostScript (para impressão), HTML, HTML Help e JavaHelp. Podemos ainda criar documentos múltiplos com o mesmo conteúdo, mas orientados para diferentes utilizadores ou sistemas operativos distintos. Isto permite ao utilizador manter toda a informação num só ficheiro, em vez de ser em múltiplos documentos.

Já que os ficheiros do DocBook são em XML, podemos sempre editá-los em editores de texto ou de XML. Alguns escritores usam Emacs com os pacotes nXML ou psgmlx. Outros usam Vim, em conjunto com um ou dois scripts. Este tutorial explica como usar o Vim como um dos editores DocBook. Vex, um editor XMl baseado no Eclipse é outro excelente editor DocBook, assim como o XMLmind XML Editor, um editor WYSIWYG escrito em Java.

Para produzirmos um melhor e mais agradável design nos nossos documentos, aplicamos uma stylesheet baseada em XSL, que, ao passar por um processador XSL, este faz o trabalho de interpretar o código XSL. Assim, os nossos documentos passarão a ser mais agradáveis visualmente e, portanto, vamos contribuír para uma melhor imagem do utilizador em relação ao software e á sua documentação.

DITA

Nos ultimos anos, o Darwin Information Typing Architecture (DITA) tem ganho utilizadores ao DocBook. Este software tem uma caracterísitica diferente de todos os outros programas de criação de documentação: em vez de se basear na tradicional escrita capítulo a capítulo, o DITA estrutura a documentação por tópicos inidividuais que o utilizador pode combinar e re-usar em diferentes tipos de documentação e em diferentes formatos. Podemos usar o DITA para criar qualquer tipo de documentação, mas este tem uma certa apetência para criar conteúdo Web, ajuda online, computer-based training e FAQs.

Já que o DITA também é baseado em XML, podemos usar qualquer editor XML para criar e editar os documentos DITA. Muitos dos editores suportam DITA e correm em sistemas GNU/Linux.

Neste momento, a única forma de converter um documento DITA para outro formato em GNU/Linux é através do DITA Open Toolkit para Linux. O DITA Open Toolkit é fácil de usar e converte conteúdo DITA em conteúdo HTML, XHTML, PDF, ajuda Eclipse ou RTF.

Ajuda online

Nem toda a gente gosta de estar a fazer download de manuais para solucionar uma dúvida que tem em relação a um certo programa: muitos dos utilizadores preferem carregar F1 e obter logo ajuda. Embora as ferramentas em GNU/Linux não se possam ainda comparar ás mesmas em Windows, já existem algumas que fazem sucesso dentro e fora da comunidade e ajudam o utilizador a escrever ajuda online.

O QuickHelp, uma das mais populares em criação de ajuda online, é uma aplicação com vertente gráfica que ajuda os escritores de material técnico a escreverem tópicos de ajuda de forma simples. Esta aplicação permite-nos ainda juntar os tópicos a um sistema de ajuda profissional, que inclui navegação, index e até um pequeno motor de busca. O maior problema desta aplicação é que é paga para ser utilizada, ou seja, não é uma software livre.

JavaHelp é uma aplicação desenhada para fornecer ajuda online para software escrito em Java. É um sistema poderoso e flexível, e em GNU/Linux podemos encontrar montanhas de ferramentas de criação de sistemas JavaHelp. Como exemplos temos o JHelpDev e o JHelp Builder, que fornecem um ambiente gráfico no qual podemos criar tópicos de ajuda e todos os ficheiros de suporte necessários a um sistema JavaHelp. De salientar que o DocBook XML pode tambem produzir JavaHelp.

O HelpSetMaker é uma ferramenta gráfica de ajuda que produz ficheiros em HTML, em sistema JavaHelp, ou em LaTeX. O utilizador simplesmente escreve tópicos de ajuda na interface e pode adicionar imagens assim como hiperligações. O maior problema do HelpSetMaker é que a interface não é intuitiva o suficiente, em comparação com o resto das funcionalidades da ferramenta.

Se o utilizador precisar de criar ajuda para multiplos sistemas operativos, deve considerar a aplicação WebHelp. WebHelp é um bom método para criar ajuda online ou documentação no browser. O formato WebHelp foi popularizado com o programa Macromedia RoboHelp e está em alta no mundo de GNU/Linux.

Documentação do programador

Para programadores, criar documentação para código é um trabalho duro. Na verdade, é a mais difícil de todas as tarefas de documentação.

Mas para facilitar a tarefa do programador, existem ferramentas que fazem esse trabalho, e, portanto, geram documentação de código-fonte. Programas como o Doxygen, DOC++, ROBODoc e o NaturalDocs são ideiais para realizar esta árdua tarefa. Cada uma destas ferramentas cria documentação em diferentes formatos para diferentes linguagens, incluíndo C/C++, Perl, Java e IDL.

Apesar de fazerem uma parte da tarefa, estas ferramentas não fazem todo o trabalho. Os programadores têm de comentar o código que escrevem e precisam de adicionar exemplos e informação extra para que estas ferramentas organizem essa informação sob a forma de documentação de ajuda. Assim sendo, estas ferramentas facilitam o trabalho do programador, mas é sempre necessário dar informação suficiente às mesmas para que elas façam aquilo para que estão programadas.

Outras ferramentas

Criar documentação não é só e apenas escrever. Criar documentação tambem envolve trabalho gráfico e com ilustrações, assim como capturar screenshots. Portanto, para conciliar todas estes factores paralelos com a criação de documentação vamos precisar de mais aplicações, entre elas algumas bem conhecidas.

Se precisarmos de editar imagens, o GIMP é a melhor ferramenta do ramo em GNU/Linux. Para além de ter o poder de editar imagens, este programa permite ainda tirar screenshots para dar exemplos na documentação. Outra aplicação a considerar é o Krita, o editor de imagem que faz parte da suite de aplicações KOffice.

Para ilustrações e flowcharts, algumas das melhores aplicações de GNU/Linux são o Sodipodi, Dia e Kivio. Todos eles contêm ferramentas poderosas que podem ser usadas para criar todo o tipo de diagramas. E cada uma delas pode exportar os diagramas criados para formatos mais conhecidos, como .jpeg,.gif,entre outros.

O software referido neste artigo só foca algumas das possibilidades inseridas no processo de criação de documentação em GNU/Linux. Existem centenas de aplicações criadas para este ramo que não foram aqui referidas, pelo que continuam a não ser tão utilizadas como estas. Talvez até existam aplicações bem melhores, quem sabe. É tudo uma questão de continuar a experimentar e a explorar?