Mailinglist Archive: opensuse-doc (40 mails)

< Previous Next >
Re: [opensuse-doc] Thread summary and announcement [was:The openSUSE distribution chages are way ahead of documentation?]
  • From: Sean Wheller <sean@xxxxxxxxxxxxx>
  • Date: Mon, 9 Oct 2006 22:19:18 +0200
  • Message-id: <200610092219.19171.sean@xxxxxxxxxxxxx>
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 Sundermeyer wrote:
> 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
>   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).

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
> documentation.

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
> > openSuSE.
> As stated more than once - the documentation sources _are_ available.
> With the

> upcoming
^^^^^^^^^^^^ 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
Novell SVN.

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 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 ;-).

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.

> > 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".

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
> > 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 ;-).

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.

Sean Wheller
Technical Author
To unsubscribe, e-mail: opensuse-doc+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-doc+help@xxxxxxxxxxxx

< Previous Next >
Follow Ups