What formatting language should I use for project documentation

Question

I'm planing to move project documentation for a fairly big software project from using Microsoft Word files with manual versioning in the filename to storing it in the source version control system. This would all be the type of documentation written by the developer team, release notes, upgrade instructions and administration guidelines so the format can be fairly complicated. Ideally it needs to be possible to publish it as both pdf and html.

At the moment I'm considering LaTeX or DocBook.

Are there any other formats to consider?

What are the pros and cons of these formatting languages?

Just to add what I've opted on doing (pretty much based on the accepted answer):

I'm going with DocBook as most of the developers on the project are quite well versed in webby languages such as XSL, XML and HTML so DocBook should seem familiar.

Also because I discovered it is quite well supported to automatically build the docs along with the project code using Maven (removing the hassle around publishing the docs was the whole purpose of this).

Answer 1

If you can come up with a format-agnostic way to represent the data you'll be able to defer that choice until the last minute and even change it if you need to.

Can you think of common data formats for "developer team, release notes, upgrade instructions and administration guidelines"? If you look at the documents you have, are there repeatable templates or data that you can harvest?

An XML or relational representation of a standard format could be rendered in any format you need.

Answer 2

LaTeX: is great for general formatting and for some specialties like special markup, equations, macros. But too many things to learn for begginers.

I don't like docbook - too many tags, but it is better suited for more processing (or preprocessing) using other tools.

I like to write documentation parts in ReStructuredText but it is probably too Python specific.

Answer 3

I've had a good bit of success with docutils reStructuredText, but it kind of depends on what you're trying to do. LaTeX and Docbook will produce the best looking documents. Prince will turn HTML into pretty spectacular PDFs, although it's a bit expensive.

Answer 4

It depends on what kind of time resources you want to invest in setting up your documentation infrastructure. If you have a lot of time to train your doc team, I would recommend DITA. It allows you to use the flexible Apache Ant and XML documentation. You can built html, eclipse, pdf; basically anything with a plugin available. You can also write your own for your own specific output types.

Otherwise I would recommend the ancient SGML formatting. This would also let you generate HTML and PDF output, though a lot of high-tech (like IBM) are making the switch from SGML to DITA.

Answer 5

Definitely DocBook. It's XML, can be converted to PDF, HTML or man pages with XSL (using any XSL engine). And there are lot more developers familiar with XML then with LaTeX.

Answer 6

I recommend the answers to this similar question:

http://stackoverflow.com/questions/409717/how-best-to-write

which in turn points to another similar question.

Answer 7

I must admit, I hate latex. I'll also admit that I haven't used it for over ten years. I found I was always fighting the thing, got very frustrated with trying to get something formatted "just so" and such. The mark-up rules are also quite complicated. Writing good documentation takes a fair amount of effort, and having to remember all the minutia of latex takes up brain cycles that could better be spent elsewhere. Obviously YMMV.

That being said, you might want to check out lout, which I believe is suppose to be a simpler latex style typesetter.

You might also want to look at LyX, which appears to be a WYSIWYGish editor or LaTeX.

The advantages of DocBook, DITA, HTML or any XML based system is the basic formatting rules (elements, attributes and entities) are pretty straight forward, and will be familiar to developers who have done any sort of web development, which gives a huge boost in reading the source document, even if you are unfamiliar with what the specific elements do. And it's not like we are going to run out of tools to process XML any time soon.

Answer 8

Well, to me, the main advantages of LaTeX come up when producing scientific work with equations and math. Therefore, if what you want to produce are manuals and release notes, I'm not so sure if LaTeX is the most handy language to use.