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 09:08:22 +0200
  • Message-id: <200610090908.23305.sean@xxxxxxxxxxxxx>
On Thursday 05 October 2006 18:02, Frank Sundermeyer wrote:
> What is Lessons for Lizards (LSL)?
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> The idea behind Lessons for Lizards is to have a SUSE cookbook (cookbook
> is trademarked by O'Reilly, so we cannot use that name). It should
> contain recipes for certain tasks not covered in the printed manual,
> such as for instance "How to install and configure SUSE without
> YaST", "Setting up a mailserver", "Compiling a new Kernel", etc. (these
> topics are, of course, hypothetical - I hope you get the idea).
> It is our belief, that such a book is currently missing and would be
> very useful for many users.

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

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.

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.

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.

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

To ignore this desire, as is presently being suggested, would be arrogant on
the part of those who currently decide what happens with openSuSE.

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


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

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

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

Access needs to be controlled until such time as people have made enough
contribution and have demonstrated responsability. In the interim, everyone
can checkout a working copy and svn update as and when changes happen.
Patches can at first be applied by core persons. I suggest starting with the
doc team and then adding responsible persons.


> How can I make sure my article is updated in both the wiki and the book?
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> toms, our xsl guru, has written stylesheets that convert docbook xml
> into Wiki language, so the xml source would be the single source to
> produce Wiki and "LSL output".
> At the moment. these stylesheets are work in progress and the Wiki
> output needs to be beautified manually. We hope to have a better
> version available in December. If you would like to help us with these
> stylesheets, please contact my by mail.

We developed the same thing over at Ubuntu-doc, in fact it was round tripped.
This has challenges, but is possible.

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.

Sorry if this message is contentious, but I think we need to be able to face
facts head-on and in plain view.

Hope this helps,

--
Ask me about the Monkey.

Sean Wheller
Technical Author
sean@xxxxxxxxxxxxx
+27-84-854-9408
http://www.inwords.co.za
---------------------------------------------------------------------
To unsubscribe, e-mail: opensuse-doc+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-doc+help@xxxxxxxxxxxx

< Previous Next >
References