Criar documentação profissional com ferramentas 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…

Novas áreas de estudo

Mais de um mês depois de ter escrito o último post, decidi voltar a entrar aqui no blog e escrever um texto que explique o porquê desta ausência. Acontece que estive em fase de testes e sem grande paciência para o estudo da área que mais adoro (a informática), no entanto com a chegada do Verão o tempo livre abunda e a minha mente prospera, como tenho reparado com os ultimos verões.

Vou, então, apresentar quais as minhas próximas áreas de desenvolvimento e estudo:

•  Desenvolvimento de um projecto relacionado com a comunidade Portugal-a-Programar, projecto esse que já planifiquei e já comecei a desenvolver. É algo que espero que não demore muito tempo até poder apresentar uma versão ao público e é algo que será muito útil aos programadores de todo o nosso país, espero.
• Desenvolvimento de dois websites: um para a rádio online que pretendo criar e outro website pessoal que nunca cheguei a criar.
• Desenvolvimento de um portal nacional de scores de overclocking. Este projecto é liderado por vários administradores e moderadores de vários foruns de renome nacional e estou integrado nessa vasta lista.
• Criação de uma rádio online dedicada ao estilo de música trance (um projecto muito pessoal, com objectivos a curto prazo).
• Criação de um blog exclusivo para pessoal que gosta de ouvir trance, blog que deverá ser actualizado diariamente com as músicas novas do momento.
• Estudo da área "Penetration Testing" (algo que já comecei a fazer), com integração do utilizador no BackTrack, uma distribuição Linux com uma montanha de ferramentas de remote exploiting, spoofing, remote scanning,etc.

Espero cumprir estas tarefas e apresentar alguns textos técnicos sobre as diversas áreas nos próximos meses. Pretendo tambem continuar a minha evolução na linguagem PHP e começar a abordar o Python de forma séria.

Está dada a explicação. Por agora tenho de ir estudar (e não vou aproveitar a praia deste radiante Domingo, devido aos estudos…) porque ainda tenho dois testes para a próxima semana (ultima semanita de aulas).