

Ask HN: documentation format? - binglo

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?
======
crystalarchives
Depends 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.

~~~
binglo
Definitely beautiful pdf output, but I was never happy with the available
"latex2html" converters.

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.

------
bayareaguy
I 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.

------
wallflower
The 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.

<http://dita.xml.org/getting-started>

------
jakewolf
Something 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?

~~~
binglo
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.

------
chaostheory
there's an open source format (not software) that is pretty comprehesive
(though at times repetitive): <http://readyset.tigris.org/>

~~~
binglo
Those seem to just be a collection of html files where you can edit them and
fill in the blanks. I guess if you like having your docs in raw html, it could
be useful for those who have a hard time choosing where to begin. Thanks.

~~~
chaostheory
well there's a non-free tool assoc with it that spits it out in dif file
formats (html, word, pdf, ...)

<http://www.readysetpro.com/>

------
dfranke
Docbook.

~~~
binglo
Why do you use docbook?

------
bugmenot
<http://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, ...).

~~~
binglo
That's quite nice. Still not sure how I feel about wiki-style plain text
markup formats though. I like them for simple and short docs, emails, and
README's because it looks good in the editor, but it seems like the more you
ask from that sort of format, the weirder things begin to look as you add
features to support writing larger docs (and you end up with more syntax to
memorize as well).

Thanks for the heads-up.

------
kingkongrevenge
POD. Learn it in 10 minutes. Generates all formats. Embeddable in code, if
appropriate.

<http://perldoc.perl.org/perlpod.html>

~~~
binglo
Yes. Thank you. I like POD for man-page -style docs, but for longer multi-
section docs I'm not sure it buys you much more than plain text (except that
you can easily convert to other formats). Also, it's harder to read than plain
text -- though maybe easier than docbook xml.

The POD docs I see as html are just single long html pages. I realize this is
just an implementation issue though.

