[oi-dev] Documentation Systems

[Tobias Famulla]

Dear Developers,

As I promised in a mail before, I was searching for some information
about document formats and system for the documentation.
I summarized information about reStructuredText, DocBook and DITA.
The summary is attached to the mail.

I did not compared these formats to pure latex, because I do not see any
advantages of using it for documentation and a lot of people know latex
already.

As a conclusion of my research I think every way has it pros and cons.
reStructuredText in connection with Sphinx and Mercurial or git is very
easy to set up and use, but the management might be easier with DITA if
you have a huge amount of documents or topics in different languages.
I think in every case, we have to install some tools and an
infrastructure and maybe have to code some scripts for our workflows.

Maybe the best way would be, to discuss the technical issue on the list
and make a decision at a upcoming meeting.

Sincerely,

Tobias Famulla
-------------- next part --------------
A non-text attachment was scrubbed...
Name: DocumentationSystems.rst
Type: text/prs.fallenstein.rst
Size: 4754 bytes
Desc: not available
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110801/179f8f6c/attachment-0004.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: documentationSystems.pdf
Type: application/pdf
Size: 53380 bytes
Desc: not available
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110801/179f8f6c/attachment-0004.pdf>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: uni.vcf
Type: text/x-vcard
Size: 121 bytes
Desc: not available
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110801/179f8f6c/attachment-0004.vcf>