[OpenIndiana-discuss] Documentation-Project

[Deano]

Hi Tobias,

Glad you picked OI to do your course on, OI is a young project compared to
many and as such hasn't yet fully formed decisions and modalities.

A quick synopsis is that, OI has a council, that would vote on major items.
With those on the council being nominated from the community. So far this
hasn't been necessary in any big way, so remains largely a system in theory.
Everything is open, with all log, discussion and development being visible
to all. A weekly meeting is held, which the developers discuss various
tabled items and issues, again anyone is welcome to sit in and logs and
synopsis's are placed on the wiki.
The mailing list and IRC channels provide most of the communication, and
anybody interested in the project that hangs around them for a bit will
quickly get a feel for how the community works.
For source control, currently the amounts of people submitting changes
hasn't needed a strict policy and its all sorted our via the oi-dev IRC
channel.

Informally a few people have mentioned we need a better documentation
system, as currently is just adhoc written directly in the wiki. Idea world,
a few people who knew various systems such as sphinx and a few others could
perhaps mail the oi-dev list with suggestions and recommendations on what to
use. In many ways the technical merits of each system isn't really that
important (they all produce html, pdf, etc.), what is, is someone who knows
a system well and is willing to help and possibly mentor others into using
it.
For all its issues, HTML does have one advantage is that has many wysiwugs
and most of us at one point have dabbled a bit.

The biggest challenge of documentation is first writing it *and* then
maintaining it. 

Bye,
Deano


-----Original Message-----
From: Tobias Famulla [mailto:ebay at famulla.eu] 
Sent: 26 May 2011 14:55
To: Discussion list for OpenIndiana
Subject: [OpenIndiana-discuss] Documentation-Project

Hello OpenIndiana-Community,

I am in an Open-Source-seminar at University, in which we have to hold a 
presentation about an Open-Source project and participate in the 
development-process of this project.

I chose OpenIndiana for this Course, because I think it is an 
interesting young project and the developement of a free Solaris is 
important for the open-source-community.

Becaus it lacks in a good documentation of OpenIndiana yet, as far as i 
read in the wiki, I had the idea of writing a script to transform the 
latest OpenSolaris documentation  from XML to a 
Sphinx-documentation(restructuredText) and rewrite it in some parts. I 
think Sphinx is a wonderful tool to write a good documentation and 
export it to html and pdf. It might be easier to handle these documents 
than the XML ones.

If you like the idea of writing the OpenSolaris-documentation in Sphinx, 
it might be helpful to integrate it in the revision control system to 
have an easy way to manage the documentation.

On another point, it would help me for the presentation, if someone 
writes me, how decisions for the project are made and how the project is 
managed(commitments to the sourcetree and something like that)

Sincerely yours,

Tobias Famulla

_______________________________________________
OpenIndiana-discuss mailing list
OpenIndiana-discuss at openindiana.org
http://openindiana.org/mailman/listinfo/openindiana-discuss