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: Frank Sundermeyer <fs@xxxxxxx>
  • Date: Mon, 9 Oct 2006 21:25:18 +0200
  • Message-id: <200610092125.18962.fs@xxxxxxx>
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@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-doc+help@xxxxxxxxxxxx

< Previous Next >