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?
Ask HN: documentation format?
1–10 of 16 posts
Re: Ask HN: documentation format?
#2Something formatted for 8.5" x 11" paper for printing out as a pdf and easy to navigate/search html.
How long are we really talking about?
Re: Ask HN: documentation format?
#3The writers at my company use Framemaker - it's pretty industry standard and expensive. They have started writing the documents using DITA. It's pretty powerful.
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.
Re: Ask HN: documentation format?
#4Something formatted for 8.5" x 11" paper for printing out as a pdf and easy to navigate/search html. How long are we really talking about?
I find that a plain text file longer than about a dozen pages in a terminal window -- containing more than a handful of sections and subsections -- becomes a pain in the neck to efficiently navigate around (during both reading and writing). A non-technical person might be reading such a document using Notepad.
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.
Re: Ask HN: documentation format?
#5http://docutils.sourceforge.net/ is quite nice: A rich set of features, easily extensible by custom directives, Python, and a hell lot of export formats (LaTeX/PDF, HTML, S5 slideshows, ...).
Re: Ask HN: documentation format?
#6Docbook.
Re: Ask HN: documentation format?
#7Docbook.
Why do you use docbook?
Re: Ask HN: documentation format?
#8Depends on the type of documentation, but I'm a fan of LaTeX since there are so many tex2____ programs out there that'll convert LaTeX to whatever format you want.
The learning curve is steeper but the flexibility is high.
Re: Ask HN: documentation format?
#9there's an open source format (not software) that is pretty comprehesive (though at times repetitive): http://readyset.tigris.org/
Re: Ask HN: documentation format?
#10I currently use Scrivener, MultiMarkdown, TexShop, MacTex and OmniGraffle if I have a diagram or two.
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.