Sobre a estratégia de documentação do projeto Office Eclesial Open Source
Alexandre Magno Brito de Medeiros
Vamos falar um pouco sobre documentação.
Eu baixei todos os documentos ODT do projeto Office Eclesial Open
Source, para estudar, conhecer o projeto. O procedimento foi muito
entediante. Então, diante das dificuldades técnicas com a instalação
do GForge, e imaginando que outras pessoas possam ter a mesma
necessidade de conhecimento daquela documentação, até mesmo para
podermos discutir aqui nesse grupo, resolvi empacotar em um ZIP e
disponibilizar na seção arquivos -
http://groups.google.com.br/group/openriial/files. É o arquivo
documentacao.zip.
Observei como está sendo implementada a documentação, em termos
tecnológicos. Quero compartilhar idéias sobre um opção diferente: o
Docbook. Mas não vou me alongar em explicações; preferirei linkar
alguns sites, fazendo breves comentários.
Uma noção simples sobre o que é o Docbook: http://es.wikipedia.org/wiki/DocBook
DocBook é um DTD para documentação técnica universal. É um padrão
aberto OASIS que utiliza SGML ou XML. Ele permite conversões para PDF,
PS, TeX, XHTML, HTML, HTML Help, Java Help, Man Pages (GNU/Linux),
TXT, Texinfo, OASIS OpenDocument (através do docbook2odf) etc.
Observemos http://wiki.docbook.org/topic/DocBookXsltPublishingModelDiagram.
Explicando
Um arquivo Docbook (XML) é escrito por nós. É um documento. Um
processador XSLT (saxon, Xalan, xsltproc etc), obedecendo a XML
Catalogs e XML DTDs, gera HTML de única página, HTML de múltiplas
páginas ou uma descrição de documento específica de plataforma chamada
XSL-FO.
Os arquivos HTML podem ser visualizados como são, ou ainda originarem TXT.
O XSL-FO ainda servirá para novas transformações: PDF, TeX, Postscript etc.
É muito versátil!
O projeto do gerenciador de banco de dados Firebird usa DocBook para
sua documentação. Estudar as orientações deles podem nos ajudar muito
a entender o DocBook:
http://www.firebirdsql.org/manual/pt_br/docwritehowto-writing-docbook-pt_br.html
http://www.firebirdsql.org/manual/pt_br/docwritehowto-docbook-intro-pt_br.html
http://www.firebirdsql.org/manual/pt_br/docwritehowto-docbook-authoring-tools-pt_br.html
Seguindo o mesmo raciocínio, esse texto do Projeto de Documentação do
FreeBSD pode ser muito útil também:
http://doc.fug.com.br/doc/pt_BR.ISO8859-1/books/fdp-primer/sgml-markup-docbook.html
Alguns sites importantes sobre o assunto, onde podemos encontrar muita
informação:
http://www.docbook.org
http://docbook.sourceforge.net
Um passo-a-passo de início rápido para quem usa um sistema GNU/Linux
[baseado em] Debian:
$ sudo aptitude install docbook-utils
$ docbook2<formato_desejado> arquivo.xml
Onde o formato_desejado pode ser: dvi, man, ps, tex, txt, html, pdf,
rtf, texi.
Para mais informações:
$ man jw
Exemplo de uso:
$ docbook2pdf exemplo.xml
O comando acima irá gerar o arquivo exemplo.pdf já convertido.
Não podemos esquecer que existem muitas outras opções para criação e
manutenção de documentação. Eu gostei dessa "síntese" aqui:
http://blog.invisivel.net/2007/03/01/latex-wikis-docbook-e-que-mais/.
Linkando ela estou economizando um pouco de tempo!
Eu nem pesquisei tanto, mas outra página que pode ajudar com
comentário é http://deathseeker25.wordpress.com/2006/06/28/criar-documentacao-profissional-com-ferramentas-em-gnulinux/.
Se você concordarem, eu posso passar nossa documentação pra Docbook.
Ela pode ser versionada com SVN ou com CVS. O que acham? Obs.: não
tenho experiência com a tecnologia, mas em teoria eu sei usá-la, e
tomo partido da opção, pelas várias vantagens e devido a ponderações.
Entretanto, eu não posso me comprometer com o "refinamento" (em termos
de customização de estilos etc) da implementação, apenas com o básico,
ou seja, colocação pra funcionar os documentos.
Por favor respondam-me se eu posso investir em Docbook. Ou então vamos
discutir os prós e os contras. Caso eu fosse fazer, faria localmente,
depois enviaria um ZIP pra vocês. Já que enfretamos as dificuldades
com o GForge.
Alexandre Magno
Cabaña Daniel
equipo de trabajo.
Más allá de lo que sea analizado, quiero remarcar la importancia de tener en
cuenta que el plan de trabajo inicial ha insumido un gran trabajo sobre
Gforge, por lo cual creo que es muy importante conocer mejor su forma de
trabajo y aprender a utilizarla bien antes de ver otras soluciones.
Seguramente hay otras soluciones que pueden ser complementarias, pero
ciertamente debemos analizar bien cada paso sin apresurarnos para obtener
resultados sólidos y seguros a futuro.
Todo lo que estudiemos y decidamos bien hoy impactará positivamente en
OpenRIIAL.
Saludos,
Daniel
-----Mensaje original-----
De: open...@googlegroups.com [mailto:open...@googlegroups.com] En nombre
de Alexandre Magno Brito de Medeiros
Enviado el: martes, 28 de octubre de 2008 09:44 p.m.
Para: open...@googlegroups.com
Asunto: Sobre a estratégia de documentação do projeto Office Eclesial Open
Alexandre Magno Brito de Medeiros
>
> el plan de trabajo inicial ha insumido un gran trabajo sobre
> Gforge, por lo cual creo que es muy importante conocer mejor
> su forma de trabajo y aprender a utilizarla bien antes de ver
> otras soluciones.
Realmente.
Eu me preocupo com isso: com as dificuldades atuais que vocês
dizem estar enfrentando para manter o GForge; em conhecer o modo
como as soluções pode conversar e sobre o quanto interações ou
adaptações entre as soluções podem custar.
Para isso, aprender a forma como as soluções trabalham é muito
importante; um conhecimento teórico. Alguma prática também. Mas
eu discordo sobre necessitarmos nos especializar demais em uma
ferramenta para somente então olhar para outras ferramentas.
Prefiro comparar soluções abstraindo sobre o que elas oferecem.
E o que procuramos? Acredito que, em síntese, seja:
- Controle de versão (SVN, CVS etc)
+ Código fonte
+ Documentação (com XML ou TeX) ?
- Repositório para multi-projetos
- Acesso remoto ao sistema de arquivos
- Interface web
- Multi-usuário
- Wiki (?)
- Interação entre usuários
- Tracker
Basicamentoe foi o que identiquei até agora para o Office Eclesial
Open Source. Por favor, em nosso raciocínios vamos tentar enxergar
o OpenRIIAL como uma coisa e o Office Eclesial Open Source como outra.
> Seguramente hay otras soluciones que pueden ser complementarias, pero
> ciertamente debemos analizar bien cada paso sin apresurarnos para obtener
> resultados sólidos y seguros a futuro.
Soluções podem ser "complementares", como é o caso de do Docbook e o
controle de versões (SVN ou CVS). E soluções também podem apresentar
um certo "paralelismo" entre si, como eu coloquei [na msg 3] em
http://groups.google.com.br/group/openriial/browse_thread/thread/dc622c4a3058b43f?hl=pt-BR
Alexandre Magno
PS.: escrevemos Docbook com arquivos de texto simples (XML), facilmente
controlados por uma gerenciador de controle de versões como SVN ou CVS.