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

[Ken Gunderson]

On Sun, 2011-06-05 at 16:19 +0100, Bayard Bell wrote:
> 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.

I'm less concerned with transforming from docbook to sphinx than the
other direction: spninx to docbook, or sphinx to Latex, HTML, or
whatever.  If Tobias wants to use Sphinx AND we can transform his Sphinx
output to Docbook (perhaps via Latex intermediary)... I say, turn him
loose on it lest the clock run out on his project due date.

> > 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?

For me the biggest barrier would be knowing what I'm talking about when
it comes to OI as my Solaris experience is minimal.  Hence, I might be
more effective helping out on e.g. editing than actual documentation
creation.  At least initially.  Indeed, part of my motivation for such
is to learn more about said platform. 

I don't know Latex, but have an interest in it.  I've "played" with
docbook a bit a few years back but far from conversant.  I would be fine
with learning more about either.

I need to go back and review the email Alan sent about this. While I
think it's past time for OI to make a break from Oracle/Solaris, I also
think we should maintain ability to leverage existing verbiage, so we
should use compatible tools.


-- 
Ken Gunderson <kgunders at teamcool.net>