[oi-dev] Fwd: [OpenIndiana-discuss] Documentation-Project

[Ken Gunderson]

On Mon, 2011-05-30 at 08:24 +0400, Garrett D'Amore wrote:
> Switching to another less popular doc format doesn't seem like a great idea.  I don't work with the documentation frequently, but I'd ask people that do.
> 
> One thing is that some of these formats are like fads... they come and go.  I remember not long ago when SGML was all the rage. :-)  From my perspective it would be good to have a format that has good tools available (multiple implementations, at least some of which are portable to other platforms), displays nicely, and provides some basic structure capabitilities to assist in parsing for content or format conversion (e.g. to HTML).
> 
> If you make me install a bunch of new tools, or learn a format that nobody else uses, I probably will be less inclined to write documentation.  (That said, I've not written much except a few man pages, and the format of *those* is relatively constrained by the need to be able to display them with the man command. :-)
> 
>   -- Garrett D'Amore

I would think Docbook would be the way to go.  Yeah, it's going to
require some specific libraries and tools but it's transformable to many
different formats.  I haven't dealt with it for a while now but easily
to morph to man, text, html, and pdf, which I think pretty much covers
all reasonable bases.

XML situps are a pain after the first few thousand.  Last I looked most
good XML editors out there were proprietary. All fine and dandy if
you're a commercial corp with a documentation staff but such would seem
to raise the bar w/o much of any real gain for a small FOSS project.

Else maybe the old standard Latex, wh/facilitates same, and although out
of vogue at present, I don't think it's not going to disappear anytime
soon.  Advantage here might be that lots of science and math types will
already be somewhat familiar w/it from thesis writing and such, but I'd
also think this would not encompass a significant number of OS/IllumOS
contributors.

I've never heard of Sphinx.



My $0.02, fwiw.