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: Thu, 5 Oct 2006 18:02:06 +0200
  • Message-id: <200610051802.06709.fs@xxxxxxx>

this thread took many twists and turns, so I'd like to summarise what
has been discussed so far and comment on it. I would also like to
explain the differences between the documentation that is shipped with
the openSUSE distribution and the Wiki. Last but not least I will
announce a future documentation project (Lessons for Lizards, LSL), that
will hopefully address some of the critics issued in this thread.

For those who know me from the opensuse-wiki list (hello Rajko, jdd and
Christian ;-) ): I am not only part of the wiki team - my primary
function is being a writer on the SUSE documentation team.

Shipped manuals vs. openSUSE wiki

Current state is, that we have two kinds of documentation for the
openSUSE distribution:

* shipped manuals
* openSUSE wiki

The approach of the shipped documentation is to guide the user through
the installation (Start-Up guide), to give a general overview of the
user interface (KDE and GNOME guides), to enable him to configure and
run enhanced services (Reference guide, AppArmor). It is designed to
help the majority of users, regardless of knowledge, hardware, etc.
The documentation is updated with each openSUSE release (approx. every
6-8 months).

The shipped manuals are written by the Novell/SUSE documentation team at
different sites across the world. They are derived from the "official"
product documentation of various Novell/SUSE products. Because product
documentation has to follow a product specific structure, company
internal styleguides, QA and other internal processes, it can't be open
in the usual sense. Consequently the derivative shipped with openSUSE
also can't be fully open, too.
So there are only limited possibilities for the community to
participate: via bugzilla, Novell doc comment system or via this list.
Furthermore we welcome everyone who is willing to contribute for a
certain topic on a case by case basis.
Please also see the LSL announcement at the end of this mail.

The XML sources are shipped with the opensuse distribution (therefore it
is possible to send us patches), the DTD is available from NovellForge
(see for details).

The (majority) openSUSE documentation has a different approach. A lot of
articles are designed to help with problems with specific hardware or
configurations. Part of the documentation on openSUSE also present
solutions for bugs or explain how to enhance the distribution and how
to use unsupported stuff like, for instance, Xgl. Other articles
illustrate the configuration of services not covered in the shipped
manuals (e.g. setting up a mailserver). In the ideal case the openSUSE
Wiki documentation is updated whenever there is need to.

It is our (that is the documentation team) belief, that the
documentation on the openSUSE Wiki is the ideal and indispensable
complement. The fact that the openSUSE Wiki documentation is - at least
theoretically ;-) - always "bleeding edge" is the main reason for the
fact, that it is not shipped with the distribution. Some articles would
probably already be outdated the day the iso images are published. For
this very reason we stopped shipping the SDB (Support database) with
S.u.S.E. Linux a few years ago.

It is also our belief that it is absolutely necessary to have two
different sources for documentation - a "static" one that is shipped
with the distribution and a flexible one that is available online. In
fact this is the case since at least S.u.S.E. Linux 4.2 (1996) when the
SDB was born on

Thread summary
(lines with my comments are starting with "# ")

1. Content

1.1 Documentation is not up-to-date due to the rapid development process
and the fact that documenting software is not too popular with

1.2 Version specific FAQs are missing

1.3 The software itself (man pages, help files etc.) is poorly

2. Structure/Organisation

2.1 A general concept on how to organise documentation on the openSUSE
Wiki is missing.
Solution 1 (Rajko): The structure should depend on the openSUSE
versions - either use a directory based
structure or name spaces

# Lot's of documentation is not necessarily
# version specific, so such a structure will
# make it difficult to maintain such documents

# This issue has been brought up frequently and I agree that it is
# one of, if not _the_, most important issues that is to be solved
# for I would suggest to move this discussion to
# opensuse-wiki, because there are more people participating in that
# list and because it was brought up on that list in the past. It
# was my plan to revitalise this discussion once the 10.2
# documentation is out the door (mid October) and the new starting
# pages are in place (Oct 20th, hopefully).
# In this context we should IMHO also discuss the search function,
# because a wiki is not the best solution when you want to have
# structured documentation. A real good search engine helps.
# If you want me to start and moderate the discussion (as I did with
# the starting page discussion), please give me another two weeks...

3. Participation

3.1 Motivation to contribute is low because the openSUSE Wiki
documentation content is not shipped with the distribution.

# See above - the main advantage of a Wiki article is the fact, that
# it is always up-to-date (at least theoretically). It would make
# little sense to ship documentation that is outdated. Please also
# see the LSL announcementat the end of the mail - hopefully this is
# a compromise you can live with.

3.2 SUSE keeps volunteers completely outside. We write our, they write
their, and that's it. There is no joint effort, there is no
coordination. It is not surprise that many people don't want
to waste their time in disharmonious, inefficient effort.

# Please see above and the LSL announcement below.

3.3 The SuSE documentation process needs to be public

# Please see above and the LSL announcement below.

4. Tools

4.1 A Wiki is a "content Motel" that makes it almost impossible to
convert it contents to other formats (such as XML, for instance). A
tool that produces a convertible source and is ridiculously easy to
use is needed.
Solution 1 (Sean): docbook::collab

# It is my strong belief, that a writer has to know the
# document source format he is using inside out - otherwise he will
# never ever produce data that is re-usable and convertible. This
# does not only apply to TeX, XML and the like, but also to M$ Word,
# OpenOffice and other tools.

4.2 We need a single tool that allows one to browse, read, edit, submit,
proofread documentation and that has a workflow implemented.

# You are looking for a Document Management System other than a
# Wiki. Usually very expensive and not open source ;-)

Project announcement: Lessons for Lizards

Triggered by Sean's mail in August
( we (the documentation
team) seriously started to think about how we could open up our
processes an accept contributions from the community.

As already said, existing processes make it impossible for us to open up
our complete documentation. So we came up with the idea of a project
we called "Lessons for Lizards".

We initially planned to announce this project in December, because some
basics (especially the xml to Wiki stylesheets) will not be ready until
then. This thread made us rethink that decision. Nevertheless, the
tools will not be ready before December... .

Please tell us what you think about the project - nothing is carved in
stone, yet. This is just a collection of ideas we came up with, so far.

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.

Who can contribute?
Everybody who is willing to ;-). The documentation team is also willing
to participate.

Under which license will LSL be published?
Not decided, yet - proposals are welcome (should be an open source
license, of course).

Will LSL be shipped with the distribution?
Yes, it will be treated as the other manuals shipped with openSUSE.

In which format will LSL be written?
In DocBook xml (or novdoc, which is a subset of DocBook).

In which output formats will LSL be available?
HTML, PDF, Wiki (more on Wiki below)

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
* a SVN server on which the LSL sources are hosted (read/write access
for everybody)
* a style guide
* support (on this mailing-list)

I have already written articles that would fit into the book on the
wiki. What about them?
The SUSE documentation team is willing to manually convert each Wiki
article that would fit into the book into docbook xml. Authors may
contact us through this list.

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.


Frank Sundermeyer, SUSE LINUX GmbH, Maxfeldstr. 5, D-90409 Nuernberg
Tel: +49-911-74053-0, Fax: +49-911-7417755;
"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 >