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…

Software do Mês : kdissert

Enquanto um jornalista escreve um artigo, surgem inúmeras ideias e pensamentos na sua cabeça. A tarefa mais complicada é ligar essas ideias de forma a que os leitores compreendam qual o verdadeiro significado das frases construídas. Para ajudar os jornalistas, os bloggers e os escritores a organizar essas ideias, surge o kdissert.

O kdissert, projecto liderado por Thomas Nagy é uma aplicação de mind mapping que tem como objectivo ajudar quem escreve a organizar as ideias. Poderá ser útil na escrita de teses, dissertações, apresentações e até de livros. O programa permite-nos criar um mapa de ideias, que ajuda a estruturar os pensamentos que vamos tendo enquanto escrevemos ou, se o escritor preferir, antes de escrevermos. Com a criação destas estruturas, as probabilidades de escrevermos um texto mais ordenado e com mais qualidade são maiores.

Com o kdissert, organizamos os pensamentos numa página dinâmica, criamos links entre ideias, ordenamos os conceitos, organizamos, reorganizamos, adicionamos links ou imagens,etc. Os documentos resultantes podem ser ficheiros PDF,imagens, documentos LaTex, documentos HTML para págins web, ou ficheiros OpenOffice.org Impress.

A palavra dissert em kdissert faz-nos pensar que a aplicação tem como públic-alvo estudantes universitários, no entanto este pacote é realmente fantástico para quem quer elaborar apresentações, por exemplo. Assim sendo, o público-alvo são todos aqueles que pretenderem organizar as suas ideias de modo a construírem um texto estruturado e de qualidade elevada. A última versão da aplicação está disponível no site oficial do kdissert (http://freehackers.org/%7Etnagy/kdissert/index.html).

O programa tem uma interface muito amigável ao utilizador, logo é de fácil aprendizagem. Recomendamos este programa a todos os bloggers que pretendem escrever artigos de qualidade, assim como aos estudantes universitários que têm teses para escrever.

As minhas experiencias em Linux

Antes de acabar as aulas decidi que nas férias iria ter uma experiencia longa em Linux. Já tinha visto qualquer coisa de Ubuntu 5.04 e de MEPIS, mas não me tinha esforçado o suficiente para compreender como se faziam algumas das tarefas mais básicas. Comecei a trabalhar em Linux a partir do dia 17 de Dezembro de 2005 e termino hoje, dia 1 de Janeiro de 2006. Pelo caminho tive mesmo muitos obstáculos que me poderiam ter feito voltar a um ambiente Windows. Mas o meu objectivo era mesmo testar até que ponto um informático conseguia realmente viver sem Windows.

Comecei por instalar o Ubuntu Breezy 5.10, no qual ainda me encontro neste momento. Aliás, pode dizer-se que os posts que foram colocados neste blog entre o dia 17 e o dia 1 foram todos escritos em Linux. A meio das férias decidi ir até ao MEPIS, uma distribuição de Linux muito boa para iniciantes, segundo alguns artigos que tinha lido. Estive uns 3 ou 4 dias em MEPIS e voltei novamente ao Ubuntu, visto que foi a distro que mais me entusiasmou desde o início, quer pelo facto de ter uma documentação muito boa, muito específica e pelo facto de ter uma comunidade sempre pronta a dar uma ajuda em casos extremos. Já o MEPIS apesar de ter uma documentação boa e ter uma comunidade forte tambem, contem alguns problemas de incompatibilidade com algumas placas de rede, nomeadamente a minha. Acho que foi uma das razões pelas quais saí fora do MEPIS.

Dia 17 entrei em Ubuntu e os primeiros problemas que encontrei foi saber como modificar os repositórios da sources.list, de forma a que o tráfego que gastasse fosse nacional. Facilmente encontrei solução para isso. Depois quis perceber porque razão os utilizadores que experimentavam Ubuntu com modems USB como o SpeedTouch diziam que não podiam colocar a distribuição a funcionar com internet. Após uma breve pesquisa percebi realmente que todos esses utilizadores ou estão enganados sobre o que lêem ou o que lhes dizem, ou realmente ainda não quiseram por as mãos nesta maravilha.

Enquanto estava em Ubuntu, o meu irmão recebeu uma pendrive que servia de dispositivo bluetooth para o pc. Então eu quis realmente por a funcionar essa pendrive aqui em Linux, de modo a que pudesse fazer trocas de ficheiros entre o telemóvel e o PC .

Tambem tinha lido que o Linux podia realmente ser tão bom media center como o Windows. Eu não compreendia como, visto que nem sequer uma musica ou um video conseguia por a funcionar. Mas lá pesquisei mais uma vez e encontrei soluções para o meu problema. Eram codecs que faltavam. Mas mesmo assim não consegui colocar as minhas musicas ou os meus videos a funcionar. A razão era simples: não tinha acesso ás partições do Windows. Estava a ficar farto de pesquisar e de tentar encontrar soluções para o meu problema, quando uma alma caridosa no IRC do Portugal-a-Programar me fez referencia a uma palavra mágica no mundo do Linux: Fstab. Lá fiz mais umas pesquisas e fiquei a salvo. Era mais fácil do que eu pensara.
Posteriormente, resolvi o problema das drivers da minha placa gráfica NVIDIA GeForce FX 5200 128Mb (velhinha, mas ainda está aí para as curvas). Como sou administrador de uma comunidade, instalei tambem um programa de FTP bem conhecido, chamado gFTP.

Por fim, consegui por o aMule a funcionar com filtros nacionais. E aí decidi experimentar o MEPIS, já que pelas minhas pesquisas encontrei referencia a muitas outras distribuições e passei os olhos por muita documentação oficial de outras distros.

SimplyMEPIS, uma distribuição Debian-based na qual podem navegar pela Internet enquanto instalam. A distribuição vem com o ambiente gráfico KDE como pre-definido, logo, como é típico do KDE, trás algumas dezenas de ferramentas, poupando assim o trabalho ao utilizador de as instalar (ou dando demasiado trabalho ao utilizador para descobrir do que realmente se tratam aquelas ferramentas todas). A nível visual é muito aprazível, apesar de que os meus gostos pelo GNOME ou pelo KDE não se diferenciam. Gosto de ambos. Julgo que ambos têm as suas próprias características, cada uma com a sua utilidade e beleza. Já vi começarem guerras em muitos foruns por causa do eterno debate GNOME vs KDE.

A verdade é que se souberem trabalhar com Ubuntu sabem trabalhar com MEPIS e o mesmo acontece com todas as distribuições baseadas em Debian. Os maiores problemas com MEPIS são encontrar repositórios nacionais para o apt-get e o problema de incompatibilidade com algumas placas Ethernet. E foi pelo facto do MEPIS ter problemas com a minha placa de rede que decidi de imediato voltar ao Ubuntu, onde tenho passado os ultimos dias de férias.

Considero que foi uma aventura que me instruíu muito no mundo da informática. Alem de serem código-aberto, as distribuições que testei têm todas as funções do Windows. Qualquer utilizador que faça o mínimo de esforço se adapta a este sistema operativo. O que é preciso é mesmo dedicação e paciência, alem de tempo e disponibilidade para resolver os problemas. Outra das razões que me levou a experimentar Linux foi o facto de eu ter preferências por sistemas operativos código-aberto. E é uma pena a Microsoft não abrir uma pequena percentagem do código dos seus produtos, ou não lançar produtos no mercado que pudessem ser alterados por programadores. Por outro lado é compreensível, já que a empresa é líder no mercado de sistemas operativos, apesar de apresentar um decréscimo nos ultimos anos face a alternativas como os sistemas Linux ou MAC OSX. Alem de que a Microsoft tem enfrentado todas as empresas de todos os outros sectores dentro da área da informática (segurança, base de dados, linguagens de programação) com o objectivo de aumentar o monopólio. Mas acontece que quanto mais tentam conquistar, mais são conquistadas. E já esteve mais longe da Microsoft apresentar soluções open-source, ou de abrir o códig-fonte de programas e aplicações mais antigas. Seria uma evolução muito boa se tal acontecesse. Eu acredito mesmo que um dia mais tarde a Microsoft se vai abrir ao mercado open-source. Mas talvez não passe de mais uma convicção pessoal.

Mas já estou a fugir ao assunto. Tenho alguns planos quanto a sistemas operativos a experimentar em tempos próximos. Tenho uma certa curiosidade pelo SUSE, pelo Fedora, pelo Gentoo e, principalmente, pelo OpenSolaris da Sun Microsystems. Mas isso já implicará novas leituras, algumas horas perdidas e muita vontade de trabalhar na área, facto que será reduzido com o recomeçar das aulas.

E porque é que tu não experimentas uma distribuição de Linux como o Ubuntu? Qual é afinal o grande medo? Será preguiça? Cá fica o desafio: se não souberes o que fazer para aprenderes mais alguma coisa na área dos sistemas operativos e tiveres vontade e motivação moral para o fazer, então faz o download do Ubuntu e começa já a trabalhar. Não é difícil, não dá assim tanto trabalho e faz com que o utilizador reaja com um auto-valorização no que toca ao seu lado informático. E todos nós temos um lado informático. Mas isso já é a minha vertente de Psicologia a falar por mim…

Versão Linux do Nepal ‘NepaLinux’ lançada

Com o número de utilizadores a crescer no país, Madan Puraskar Pustakalaya lançou o sistema operativo open-source NepaLinux, de modo a facilitar os problemas que as pessoas do Nepal têm com a língua inglesa. Com o lançamento deste sistema operativo, os habitantes do Nepal que utilizam software pirata podem começar a usar software do Nepal totalmente gratuito. Têm é de fazer o download e instalar a imagem do SO num CD.

O software já inclui programas como o Gaim,GIMp,Mozilla Suite, GnomeBaker CD/DVD Burning Utility, visualizadores de imagem, Jogos entre outros. O kernel do SO é a versão 2.6.12 e trás por defeito o GNOME 2.10 como ambiente de trabalho. A principal novidade do NepaLinux é o dicionário NepaLinux, com um SpellChecker e um GrammarChecker incluídos.

Na minha opinião, o NepaLinux é mais um passo no desenvolvimento tecnológico dos povos menos desenvolvidos. Apesar de muitos dos utilizadores do software não terem formação para lidar com este tipo de tecnologias, eu julgo que o facto de países como o Nepal adoptarem utilitários open-source como os principais é uma mais-valia para o país, visto que o utilizador vai poupar dinheiro. Mesmo sendo um país onde ainda se morre á fome e onde as condições económicas são influenciadas pelas condições climatéricas (lembro que o Nepal situa-se num local um pouco inóspito do planeta), optar pelo software código-aberto em função do software Windows é um primeiro passo para o desenvolvimento tecnológico do país.

Se todos os países com piores condições económicas e de fraca formação criassem uma distribuição Linux em prol de um SO Windows, o desenvolvimento tecnológico seria mais rápido e os utilizadores aprenderiam mais depressa sobre as novas tecnologias e consequentemente sobre outras culturas, outras línguas.

Não creio que a solução para os problemas políticos e económicos destes países seja a adopção de sistemas operativos código-aberto, mas, se ligarmos as coisas, conseguimos ver que pode haver relação entre a formação tecnológica e a situação económica e política de um país.

Seja como for, é de louvar este tipo de iniciativas e, neste aspecto, o governo do Nepal assim como os programadores do NepaLinux estão de parabéns…