Ask HN: documentation format?
You need to write a manual that's more than a few pages. Maybe you'd like to be able to provide the client/customer/community with html as well as pdf. What format do you use, and why?
The learning curve is steeper but the flexibility is high.
Bonus for being able to render mathematics in your docs.
Edit -- Also, I agree with you about the learning curve. Although it's very easy to get good-looking docs if you use one of the canned documentclasses and built-in commands, once you start to stray from those you're in deep water very quickly.
http://www.literatureandlatte.com/scrivener.html is a combination outliner/editor for OSX. Most of its features are focused on allowing you to manage a lot of different bits of a larger document. There's a full XSLT generation engine inside it so you can get it to generate just about anything you want if you're willing to roll up your sleeves a bit.
http://fletcherpenney.net/MultiMarkdown is a simple markup syntax (derived from Markdown) which Scrivener supports.
Scrivener and MultiMarkdown together generate HTML or LaTeX from the base document, so you need to use something like http://www.uoregon.edu/~koch/texshop and http://www.tug.org/mactex to get something worth printing.
DITA is an emerging documentation standard. It uses XML to describe the content and structure of a document. If you write your documentation in DITA XML, you can render it to PDF or online help easily. Yes, DITA is a little verbose.
How long are we really talking about?
So, we're talking about a doc that's getting a little too cramped being just a plain text file, and which might grow longer as time goes by.
Thanks for the heads-up.
The POD docs I see as html are just single long html pages. I realize this is just an implementation issue though.