On Monday 09 October 2006 21:25, Frank Sundermeyer wrote:
On Monday 09 October 2006 09:08, Sean Wheller wrote:
On Thursday 05 October 2006 18:02, Frank
At the moment, we have two branches of documentation for openSUSE, both
of _equal importance_: the openSUSE Wiki and the shipped documentation.
I am focused on 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
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
* 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).
The jam is understood. The breaker is that you don't want to parse the Docbook
XML using the openSuSE profile to produce a new set of Docbook XML containing
only openSUSE and then place that into community SVN. Reasoning, you would
have to merge changes from community SVN back into Novell SVN.
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.
I see that. This makes me think that if internally you are not able to give
community only openSuSE documentation, then community willing could transform
the XML to new XML (openSUSE only) and proceed regardless of the internal doc
effort. Community could also produce its own doc RPM.
Just thinking aloud as though the shoe would be on the other foot :-) I assume
that shut a fork would not meet with internal approval and would therefore
not be recognized as official.
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 ;).
That's a relief :-)
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
What I am saying is that the source (SVN) of the source (XML) is not available
to persons outside of Novell. As a result during development, it is not
easily possible to get hold of updates done to the documentation source until
such time as it becomes available in RPM and this, while understandable, is
contrary to an open development model.
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
As stated more than once - the documentation sources _are_ available.
^^^^^^^^^^^^ until then is there a
way to contribute?
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.
Correct. The process of being able to collaborate on documents during
development phases is hindered by the fact that community cannot access the
Sure the source is in the RPM, but that is a delay in the process and means
that contributive changes can only be made once a RPM is available.
If openSuSE wants a community relationship in the
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 ;-).
I agree your license is open. What I am saying is that the development process
is not. I am sure you will agree that it is much easier to develop when
everyone can see the changes before packaging.
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".
It would be better to have at least a working copy, without commit access, of
the source during development. At least then changes can be viewed and
contributions made in a more productive manner. Tasks could be identified,
published and shared amongst anyone in the community wishing to take on a
task. Patches can be checked and approved/disapproved by internal members.
To ignore this desire, as is presently being
suggested, would be
arrogant on the part of those who currently decide what happens with
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 ;-).
Understood, but from openSuSE community perspective, does anyone really care
about Novell documents? Personally, I don't, so I am not really concerned
with how community contributions end up in Novell products. The interest is
with openSuSE not NLD or other stuff.
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.
When you customize the DTD it is no longer Docbook :-) It is Novdoc.
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).
I think I am looking to get involved before the build services. Before the
fact rather than after. Perhaps I stand alone in this sentiment. If so then
let me rather shut my mouth and keep the peace. I'll go along with what you
already are already prepared to do. If I am not alone, then it would be good
to hear others voices.
Ask me about the Monkey.
To unsubscribe, e-mail: opensuse-doc+unsubscribe(a)opensuse.org
For additional commands, e-mail: opensuse-doc+help(a)opensuse.org