Good markup for writing technical design documentation

Question

What would you recommend as a good markup language for writing technical design documentation? Ideally I'd like to have at least the following from it:

• Works well in source control - I'd like to be able to keep the documentation in the repository with the source that it designs
• Able to do UML-ey diagrams and other relevant techniques in the markup - the ability to do class diagrams, code snippits and so forth in the documentation would be useful.
• Ability to generate well laid out documents from the markup easily - so that they can be generated as part of a site build along with API documentation, for example.

AsciiDoc fits on numbers 1 and 3. Docbook and TeX I've not looked into enough yet to know how well they would fit, but I was wondering if there was anything else out there worth investigating...

EDIT: By Technical Documentation, I'm talking docs that are primarily developer facing, and almost certainly not customer facing, but that potentially will be reviewed by team leaders and the like...

Answer 1

I'm not sure why I'd do anything other than use a Wiki of some sort for technical documentation.

Answer 2

There is also the Graphviz filter for AsciiDoc which gives you a way to embed textual representations of diagrams in the markup file. This may satisfy point 2.

Answer 3

Quick note about Docbook (though you didn't really ask about it): While the markup is kind of hard to write by hand (even with a good XML editor), I use it for generating multi language documentation (using XSLT to generate a single-language docbook). Works quite good so far, and you can generate both documents for printing and online help (e.g. HTML help on Windows). There are some GUIs for Docbook to make things easier. On the other hand, AsciiDoc can export to Docbook, and with Greg Hewgill's answer, this might already suffice.

My experience with AsciiDoc (though not having used it, just saw what two co-workers do with it) is that although it's quite powerful, you don't have any meaningful help while writing (i.e. no Intellisense, no fancy GUI), and it was rather hard to get a really well layouted PDF file out of it. But now it works, and it will likely be easier in the future.

Answer 4

I've had good experiences with Sphinx for developing documentation. Sphinx uses reStructuredText for markup. It was originally designed for managing the Python language documentation, but I've had good success with it for creating developer-facing docs (e.g. API references) as well as user-facing docs.

It "works well in source control" and has the "ability to generate well laid out documents from the markup easily". All of my Sphinx docs are in source control without issue and it's pretty easy to make customized templates for the (several) output formats it supports.

I've never had to "do UML-ey diagrams and other relevant techniques in the markup" with Sphinx myself, but there is a built-in Graphviz extension which ought to do the trick. And if you know a little Python, it might not be too hard to write your own extension, if that's not quite what you're after.