What would be the best documentation format taking into concern ...

Question

... taking into concern that it must be:
- revisable - small project but some numerical data will be changing from version to version, and documentation must be version dependable, and some kind of revision control is preferable (diff)
- must be printable - since, well, in the end it will be printed along with some other documents (otherwise I would just take opt for some sort of wiki)
- must be able to easily include graphs, pictures (images of all sorts in general, scanned and produced by programs)

Options:
.doc / .pdf - different to diff
wiki - problem with printing in a "normal" matter
big html file - an option, still considering it
latex - an option, but a pain to edit when it comes to positioning lots of images, and impossible to edit when it comes to something different and not expected in view of layout

So far my best idea is to go with .doc -> .pdf files, and just handle the pain with diffing them. Better alternatives ?

Answer 1

There is a GUI editor for LaTeX called LyX that is supposed to be very good though I have not used it myself.

There is also DocBook, an XML format that can be converted into a number of different output formats: .pdf, .rtf, .html, etc.

Answer 2

If you're keen on wikis but worried about print output, you could look into using Drupal and the print module to output to PDF.

Answer 3

What about DocBook? You could write the manual for a 747 with DocBook: it's the ultimate SGML (or XML; there are two versions) dialect for technical writing.

Answer 4

What's your budget? Adobe Framemaker is an industry standard documentation tool, and it supports your requirements. Most importantly, it supports the concept of books with chapters (unlike Word). It supports diffs, even in binary format. On the downside, it's expensive, has a steep learning curve, and it takes a while to configure templates.

If you want app-independent doc source, DITA is a popular standard format/framework. You can work on the docs in Frame, XMetal or similar XML editor that supports DITA, and output to multiple formats (PDF, HTML, etc), without being tied to a particular editor. The DITA project itself is FOSS, but its much more usable with a decent editor.