What's a good markup language to write user manuals in?

Question

Developers need to write some manuals. Word sucks so we're killing it as fast as possible.

So, what are good tools that people actually use?

I'm perfectly ok with, and prefer, some kind of markup. LateX is a bit over the top and IIRC, rather tricky to modify the output in.

I've looked at Sphinx (seems nice, has nice PDF, and we use Python already) and docbook (XML, ugh) and am leaning to the former. I'm sure there are other suggestions and am willing to hear them.

Note, this is not an exact duplicate of http://stackoverflow.com/questions/371654/application-not-a-markup-language-for-producing-a-user-manual. It's rather the counterpart of it. :)

Update: Not for APIs. We use Doxygen for that already. This is pure end-user functionality that needs to be described in a few books/booklets.

Answer 1

If you're looking to document your code (as in an API) then you're repeating yourself unless you generate the documentation from your source and appropriate source comments. Something like Javadoc or Doxygen would do this, but don't know what the Python equivalent is.

As for instructions and the like, what about Markdown? It's readable as plain text and can be translated to more sophisticated formats.

Answer 2

I suggest Asciidoc.

It's quite easy to learn (just have a look the Cheat Sheet) and produces very nice looking documentation, and the best thing is that the sources are also human readable.

Output formats are DocBook and (X)HTML (and with some other tools, PDF as well).

EDIT

As a Stackoverflow member, you may be better of using Markdown, as you already know most of it's syntax.

Answer 3

The answers given so far are good for API or shorter usage guides, but if you are composing a serious body of text, you need a serious composing tool. The question you posted gives a pretty good run-down of the strengths of several heavy-hitters in this category, so i won't rehash them.

If you don't have technical writers, that is to say, your documentation comes solely from developers, then you won't have much documentation. Their time is better spent on creating the product. If, on the other hand, your need for documentation is great enough that you need people who's primary job is technical writing, then they deserve (and definitely require) the right tools.

You would not expect your developers to compose their code in notepad.exe (although some of them probably do it anyway), nor will your technical writers thrive with anything but the best tools for their job.

Answer 4

Steve Streeting, the (former) project lead for OGRE, recently wrote an article about his new documentation toolchain which starts out with ASCIIDoc and ends up as PDF: Building a new technical documentation tool chain. It includes full setup instructions for ASCIIDoc, DocBook and FOP on Windows.