On Monday 09 October 2006 09:08, Sean Wheller wrote:
On Thursday 05 October 2006 18:02, Frank Sundermeyer wrote:
Hi,
I think the idea of LSL is good, but does not address the core of the problems:
* Proper recognition and addressing of community request to participate in "all" documentation development related to openSuSE.
* Willingness to address and resolve the problems that hinder release of all openSuSE documentation source
sorry for not having been clear enough. I will try again ;-): At the moment, we have two branches of documentation for openSUSE, both of _equal importance_: the openSUSE Wiki and the shipped documentation. We are _not_ able to completely open the shipped documentation for openSUSE because of the following reasons: * the manuals shipped with openSUSE are spinoffs of Novell product documentation. Product documentation has to follow company internal styleguides, QA and other internal processes like scheduled translation. Creating this documentation is tightly connected to the products with regard to structure, content and timing. It is written in close cooperation with product management by the people in the Novell documentation departments all over the world. These manuals contain parts that are suitable for openSUSE, too. These parts are used to create the manuals shipped with openSUSE. This way the shipped manuals are not exclusively openSUSE but are an excerpt from the product documentation. * we have one common repository for all Linux documentation at Novell (single source approach). As mentioned above, openSUSE is just a part of it, this repository includes documentation for SUSE Linux Enterprise Server, SUSE Linux Enterprise Desktop and SUSE Linux Point of Sale as well. * the documentation sources for the different projects are _not_ separated - most files contain parts only used for a specific product (we are profiling a lot - single source approach) Because of these reasons, it is not possible to create an open svn and accept contributions from outside. It is also not possible to completely separate the openSUSE documentation from all other Novell Linux documentation, because this would create a workload we will not be able to handle (it would be a merging nightmare). However, this does _not_ mean the community can not contribute. Apart from contributing via bugzilla and the Novell doc comment system, anybody can send us patches - the profiled xml sources are shipped with the openSUSE distribution. ---------- We did _not_ invent the LSL project in order to conceal the fact that we will not completely open our documentation - as you can see, we are pretty open about that ;). We initially came up with the cookbook idea because we are very fond of the cookbook series from O'Reilly and are using some of these books for our daily work. We thought the openSUSE users would benefit from such a book, too. We were also very much aware, that a lot of stuff that is currently on the openSUSE Wiki would very well fit into such a book. So, additionally inspired by your initial question to open the SUSE documentation, the idea for a community project was born.
Much of this thread has focused on technology, tools and the challenge of how to write, when it should be discussing the decision to make available documentation sources, that still seem to be withheld, to which members of open community wish to contribute.
This is not true - see the suselinux-manual source packages. They contain the (profiled, see above) xml sources for the shipped documentation.
It is my understanding that the intent behind openSuSE is to be an open and free distribution that is a community owned project. It therefore stands to reason that this should apply to documentation.
The idea of LSL just takes community focus off of the real problem, the inability to release all the documentation sources related to openSuSE.
As stated more than once - the documentation sources _are_ available. With the upcoming susedoc rpm package for LSL everybody will even be able to create books from these sources with just one single command. Correct me if I'm wrong, but I have the strong impression that for you everything besides "providing an svn where everybody can check in/out openSUSE documentation" means "closed documentation development". I do not share that opinion.
If openSuSE wants a community relationship in the area of documentation, then then some people should realize that unless this problem is addressed, it will always come back to haunt. The only way to address the problem is for all documentation, and the source, that would be packaged in openSuSE to be made available under open license and placed in a collaborative infrustructure.
Our documentation _is_ under the GFDL license, so everyone can do with it whatever this license allows. Not having an "open" SVN does not mean the documentation is not available under an open source license ;-).
What I am going to say next is just my feeling, though I do detect similar feelings from one or two of the people discussing here.
It is not neceserily the desire of every person to spend days and hours writing books, LSL is a case in point. Most community members want to be in a position that when they spot a problem with existing documents, they can fix it.
There are also quite a lot of community members that contribute very valuable documentation to the Wiki. LSL will give them a second platform where they will receive more recognition and which will also make it very clear how valuable their contributions are.
The important thing here is that "they can fix it" themselves. This is a key component to building any documentation community. People are not there to sit on the sides, make a few comments and hope that changes get made. They want to be a "part of" the development, and they want to have "some control" that will come with a "level of ownership". It is this level of contribution that is most valuable as it serves to provide some level of maintenance and sustainability.
In the essence, I agree with you. But to me you make it sound like "If I cannot get 100% I don't want to have anything".
To ignore this desire, as is presently being suggested, would be arrogant on the part of those who currently decide what happens with openSuSE.
There are facts to be honoured and these facts do not allow us to completely separate 50% (the other 50% being the wiki) of the openSUSE documentation from the rest of Novell's product documentation. You also have to be aware that it's a learning curve for us and LSL is a start we will surely learn from ;-).
In light of this, if openSuSE documentation efforts are to have community support, then the whole source and nothing but the whole source needs to be available under free and open license.
It already is - see the suselinux-manual source packages and the package's license information.
Furthermore, where, when and how members of the community decide to contribute is a decision for the community in conjunction with the the Documentation Team, not the Documentation Team alone.
We made one proposal - LSL. If the community has better ideas and convinces everybody, so be it. We just will not open the core manuals as is for now, so we will not reach agreement there - therefore let's talk about things that can be done ;-)
In which format will LSL be written? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In DocBook xml (or novdoc, which is a subset of DocBook).
No, novdoc is not a standard. Docbook is a standard. So is DITA.
Novdoc is 100% docbook compatible and just excludes some docbook tags.
What tools will Novell/SUSE provide? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * the complete build environment SUSE uses to build it's books (including stylesheets, scripts, etc.) as an RPM package
And as source in the SVN mentioned below.
We are not using any proprietary tools (except XEP for building PDFs (because there is no alternative), but that can be replaced by FOP- with some restrictions), but scripts instead. So there is no need for an extra source package. This package will also be available within the openSUSE build service (and therefore be under revision control, if I am not wrong).
* a SVN server on which the LSL sources are hosted (read/write access for everybody)
It's not about LSL. Nice idea, but I am looking for the current documentation sources to be available before commiting to writing new documents.
see above.
It would be better to put the xsl source in svn where people can look at it and decide if they can contribute. Once again, holding source in a hole is not the way forward for an open source community.
We have no intention of holding source in a hole. The susedoc rpm will be available on the build service and will be shipped with openSUSE (at the moment I do not know whether it will be ready for 10.2, but we will create the project on the build service ASAP). -- Regards Frank Frank Sundermeyer, SUSE LINUX GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.opensuse.org/ Reality is always controlled by the people who are most insane Dogbert --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org