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

[Bayard Bell]

On 30 May 2011, at 18:56, Ken Gunderson wrote:

> Anywhoooo... I've not checked those links yet but in general would avoid
> wiki markup.  Interesting exception here possibly being since we're
> using Atlassian wiki already.... hmmm.....  This is trouble with the low
> hanging fruit - it tends not to withstand the test of time. The advatage
> of SGML and subset docbook is that they do - with cost of higher bar of
> entry.  Why can't we have out cake and eat it too??
> 
> Latex might be worth a closer look as I suspect there are lots of FOSS
> gui'zed editors out there.  Ease of use when needed for cranking out
> text and also power for power user when needed?  Hmmm.....  
> 
> Else I do think Docbook would be best, even if initial bar is a bit
> higher.  It would not be unlike Solaris in that regard and most folks
> hereabouts seem capable of dealing with it.

I'm not sure you've understand my premise: I'm not suggesting that we reduce editing to using wikis, just that wikis can be a very usefully simplifying front-end for content that can be exported to DocBook and then republished into other formats we need. I'd bet that with a bit of nursing, we can get some of the macros we want for things like man pages working just fine in a wiki so that it's not even a question of leaning heavily on wiki markup per se. I don't mean to suggest that wiki authoring is a 100% solution, as I don't think there is a 100% solution for this in terms of editing tools. I do, however, think that we should be trying to maintain as much content as possible with a front end system that has the lowest barrier to entry in terms of toolset complexity and reserve more complex tools for content for which it is absolutely necessary. As per the cite already provided, DocBook is perfectly happy to see itself as an interchange format, so we can afford to use a range of tools, as long as that doesn't create confusion in its own right.

Cheers,
Bayard
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 1515 bytes
Desc: not available
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110530/bc759057/attachment-0010.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: PGP.sig
Type: application/pgp-signature
Size: 841 bytes
Desc: This is a digitally signed message part
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110530/bc759057/attachment-0011.bin>