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

[Ken Gunderson]

On Mon, 2011-05-30 at 15:11 +0100, Bayard Bell wrote:
> Tobias,
> 
> I was just discussing this with Deano on IRC...
> 
> My proposed litmus test is this: my girlfriend is willing to spend some time this summer helping out the project as a tech writer (she's got a background in speciality editing, although not as specialised as IT or *nix in particular). I'm pretty much with Garrett: the problem isn't that we using DocBook and should be using something else instead. If someone is interested in writing documentation, the question seems to be is there a mature toolset whose learning curve we can reduce to get someone willing able to be productive quickly. The issue is mostly one of front-end tools, and the question would thus be whether we can allow most editing to happen in a really simple format that can be marked up to DocBook for interchange, as a format that can be consumed by a PDF reader, a browser, or man. Alasdair's offered similar feedback recently. The DocBook people recognise as much: looking through some of the DocBook sites, I found the following remark:
> 
> "DocBook has the vices that go with its virtues. Some people find it unpleasantly heavyweight, and too verbose to be really comfortable as a composition format. That's OK; as long as the markup tools they like (things like asciidoc or Perl POD or GNU Texinfo) can generate DocBook out their back ends, we can all still get what we want. It doesn't matter whether or not everybody writes in DocBook — as long as it becomes the common document interchange format that everyone uses, we'll still get unified searchable documentation databases."[1]
> 
> The premise should be what simple format we can use to generate DocBook for what I'd take to be the very simple bulk of documentation tasks, preferably using a wiki-like editor. Doing some very brief research, I came up with Scroll Wiki Exporter, which would allow us to export documentation from the Confluence wikis we're already using for OI and Illumos.[2]
> 
> One way or another, the topic does seem ripe for discussion. If you're game to work with us through the decision process into implementation, how about we schedule you for a coming oi-meeting?
> 
> Cheers,
> Bayard
> 
> [1] http://tldp.org/HOWTO/DocBook-Demystification-HOWTO/x57.html
> [2] https://plugins.atlassian.com/plugin/details/7019

Aye carumba!! All you top posters sure mess up the logical flow ...

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 write fairly well, as well, and have previously given consideration to
helping out in this regard, but am not too familiar with Solaris and
that high bar remains for me.

My $0.02