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

[Bayard Bell]

On 5 Jun 2011, at 15:05, Ken Gunderson wrote:

Hello, Ken,

> I'll let Tobias speak for himself but my read was that he has a
> preference for Sphinx but willing to use other tools.

That was also my inference, provided we haven't hit a timeout for him to complete the project he needs to do for his seminar.

> I've never used
> Sphinx but took a quick look at links that Tobias posted a while back
> and it seemed like it could serve our needs pretty well.  

Nothing against Sphinx, but my immediate observation is that we're not starting documentation from scratch. As of yet, Sphinx doesn't support interchange from DocBook (there's a Google Code project for converting a subset of DocBook that someone found useful), which is the source format for the current documentation. That gives me pause. It's by no means insurmountable, but I'd like to hear why we'd want to jump through those hoops, with some reference to how this has worked elsewhere. I've taken a look at a sample from the rather extensive list of projects using Sphinx, and what I don't see so much of is large, non-Python projects like ours using it, and that also gives me pause, which is why I've tried to do some research and think that more research still needs to be done.

> You'd
> mentioned that your girl friend might be willing to contribute and I'd
> subsequently suggested she take Sphinx for a test drive?  I'd be curious
> whether she has or not, and if so, what were her impressions?

She's in the course of moving at the moment. Once she's settled (another week or so), there'll be time for a test drive.

> Iirc, Sphinx supported export to a variety of formats.  Since
> documentation is something developers are historically far less keen on
> than writing code and we've got someone interested stepping up and
> contributing in this much neglected capacity, barring any technical
> reasons to the contrary, my vote would be to give Tobias the thumbs up.

As I've explained previously, I really don't think the problem we're trying to solve looks like that. I could just as easily say: well, there's a tool already out there from ASF that converts existing DocBook content to Confluence wiki (which we probably need to do in some way so that what documentation we have is easily accessible online), there's a Confluence plugin we can get for free that can export that back to DocBook and from there to HTML, PDF, and man, problem solved. I'm not prepared to say that that's the answer any more than is Sphinx, just that evaluation criteria are different from what you suggest and the answers thus not as obvious as you take them to be. In any case, these are decisions that are made at #oi-meeting.

I think we need tools that then turn into getting people involved in documentation, this is an opportunity where we need to understand how we capitalise on that for further opportunity. You've expressed some interest in contributing to documentation: what would get you to become involved in this capacity?

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/20110605/42be31db/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/20110605/42be31db/attachment-0011.bin>