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

[Tobias Famulla]

Hello,

As Ken mentioned above, I would like to help to document OpenIndiana,
because I think it is an interesting project and I am frustrated by the
documentation of many projects and want to help to make it better.
The Tutor of our course is a little bit flexible, so it is not a
question of a few weeks do decide, what tool fit the needs of the project.

I was reading some articles(also some Wikipedia-articles) about
technical documentation and of course formats like DocBook, DITA or
Latex were mentioned there as open formats for this.
I also used javadoc for an api-documentation once, but this is for sure
not that tool we can use for such documentation.
Somewhere in the past I also recognized Sphinx, played a little bit with
it around and liked the easy way to use it and to get started. I also
like reStructuredText and the idea to easy write a documentation with a
normal editor and a lots of easier syntax than Latex. But I am not an
expert on Sphinx or used it much.

I think the most important tasks are to find a format to handle the
documentation, tools to work with it, and workflows (how can people
write some parts, how is it automatically converted to the output
formats and so on).
The focus should be on the easy use of the tools and not specially on
the format to encourage many people to write things for the documentation.

Because there are parts written by Sun, we might use them (we have to
check the licenses). If we want to use DocBook we can use them as they
are, although we could have to structure it new, and have to find good
DocBook-Tools.
An the other hand we could convert in into an easier to use format like
reStructuredText, Dita, Latex or something like this, and use tools
connected to this.

I will try to make a little research on tools for documentation soon and
send it via mail to this list.

Afterwards we can discuss the pros and cons on the list an maybe find a
solution at an oi-meeting next weeks or on the list.

Best Regards,

Tobias

Am 05.06.2011 18:00, schrieb 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.
>
>

-- 

Jabber:	boti at jabber.ccc.de
ICQ: 	279837014
Handy:	0178-5545505
Skype:	grund-rauschen

-------------- next part --------------
A non-text attachment was scrubbed...
Name: uni.vcf
Type: text/x-vcard
Size: 121 bytes
Desc: not available
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110607/f29cfd5d/attachment-0005.vcf>