POD. Learn it in 10 minutes. Generates all formats. Embeddable in code, if appropriate.
Ask HN: documentation format?
11–16 of 16 posts
Re: Ask HN: documentation format?
#12Depends 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.
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.
Re: Ask HN: documentation format?
#13POD. Learn it in 10 minutes. Generates all formats. Embeddable in code, if appropriate. http://perldoc.perl.org/perlpod.html
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.
Re: Ask HN: documentation format?
#14there's an open source format (not software) that is pretty comprehesive (though at times repetitive): http://readyset.tigris.org/
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.
Re: Ask HN: documentation format?
#15http://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, ...).
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.
Re: Ask HN: documentation format?
#16there's an open source format (not software) that is pretty comprehesive (though at times repetitive): http://readyset.tigris.org/
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.
well there's a non-free tool assoc with it that spits it out in dif file formats (html, word, pdf, ...)