Finding a file format for documentation
Your help is needed.
Currently we are looking for a file format that we can use for documentation.
There are currently 7 basic conditions our desired file format should match:
- Should render nicely in browser e.g, produces HTML.
- Should be nicely printable. e.g, format produces PDF or PS easily.
- Basic tools should be widely distro'd and installed on all standard platforms (MS, Apple, Linux).
- Sophisticated tools should be widely available and installable.
- should be diffable.
- should be amenable to version control.
- should work well with translation requirements.
below here we have a crosstab where you can add your pros and cons, further below you can add your personal ideas in text. Feel free to add any comment you have or to suggest any other file format.
file format |
pros |
cons |
plaintext |
no special editor needed; everyone knows how to handle it; can be converted into any format easily; cross-plattform |
looks boring in a browser; cannot be used to produce nice print and pdf outputs easily; version control requires special tools |
odf (OpenOffice.org) |
cross plattform; easy to learn and handle (WYSIWYG editor); nice output possible; version control available; free open source software, priceless; good PDF export with various options |
HTML output isn't nice at all ...; Layout changes require a lot of work; Output is sometimes different from the layout; Pictures tend to "rearrange" automatically sometimes ...; Requires big installation |
LaTEX |
cross plattform; perfect output; easy HTML conversion; perfect for large documents, one tool for HTML, PDF / Printoutput and presentation (Beamer); typical scientific style outputs |
learning Latex requires some time; people using it love it, people not yet using it hate it ...; version control requires addon (free tools available); publishers usually accept the PDF output but not LaTEX itself |
asciidoc |
|
|
HTML |
no special editor needed; basic tags easy to learn; ideal for web publishing |
WYSIWYG editor tend to produce not so nice HTML output; PDF / Print Output looks boring; Version control needs special tools; complex layouts (books, articles, guidelines) tough to set; does not support translations |
PHP |
supports translations; no special editor needed; basic tags easy to learn; ideal for web publishing |
Language tagging with a simple PHP function; WYSIWYG editor tend to produce not so nice HTML output; PDF / Print Output looks boring; Version control needs special tools; complex layouts (books, articles, guidelines) tough to set |
personal ideas
Personal opinion of Jens Paul: While having a few benefits, I think plaintext and HTML has too many drawbacks, especially when it come to areas where we need a nice print / PDF output. I personally would prefer LaTEX or OpenOffice. LaTEX is way better to produce a perfect, equal output along all documents, while OpenOffice has the benefit that it is way easier to learn. Both arguments weight 50:50 in my opinion, but I guess most of our community members won't work with LaTEX. Therefor my vote goes to Open Office (with a wining eye, as I prefer LaTEX) ....
personal note of H. Heigl: I think we have to mention two things: a) documentation for what exatly (internal, external, FAQ, HowTo, etc.) and b) then the File Format (txt, html, pdf, etc.) My 2Cents to point a): keep it simple. every one should be able to write on it. plain txt or OO should do it. My 2Cents to point b): txt or Odt for editable Formats and PDF for noneditable like handbooks, Policys or so wich would be published.
personal note of Alejandro Mery: I think AsciiDoc is the perfect because people only needs a plain text editor and to know a very simple markup, which is also nice to read directly. AsciiDoc file are trivial to edit and authors don't need to worry at all about formatting, and is easily converted to DocBook which opens the door to many output formats, and consistent documents. As a drawback, to see the final document you need to produce it each time using the DocBook toolchain.
personal note of Philipp Guehring: I think the deciding factors are the translations into all the languages and the versioning, since both issues can cost us a lot of time and hassle, if not supported properly. I would hope that we could find a better solution than PHP for proper translation management. Perhaps we could adapt a Wiki engine (which has versioning included), or OpenOffice ...
SunTzuMelange: One Billion Browsers can't be wrong ... HTML is by far the most popular format we have. As a *presentation* format it is "good enough" except for real information distribution. Where it looks poor is in printed form, with lots of graphics, or on some flashy website. But that has nothing to do with its core ability to do the basic information distribution task.
PhilippGuehring: I just saw that OpenOffice 2.3 is able to save Documents to MediaWiki format. I guess that might be a move to make MediaWiki´s wiki-format the standard wiki-format, and might be an option for us. We should research into those integration possibilities of OpenOffice 2.3