Re: [opensuse-marketing] The openSUSE Handbook proposal

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view

Re: [opensuse-marketing] The openSUSE Handbook proposal

Frank Sundermeyer
On Wed, 29 Sep 2010 20:27:11 +0200 Javier Llorente wrote:


(Disclaimer: I am working in the SUSE documentation department and am
the person leading the openSUSE documentation project in our department)

I am not reading opensuse-marketing (doing that now ;-)), but henne
pointed me to this thread, therefore I did not answer earlier...

Please move this discussion to opensuse-doc, where you can reach all
people currently writing the openSUSE manuals as well as other people
interested in documentation

> I was thinking that having an openSUSE Handbook (or handbuch ;)

well, this may come as a surprise to most of you, but we already have
that - and it's even shipped with each openSUSE version. The problem is
that it is kind of a stealth documentation because it is almost
impossible to find it when you do not know where to find it.

The fact that most of you having participated in this thread are not
aware of the existing documentation is proof for that.

The documentation team has fought for a better visibility of the
documentation for years with to avail - it would be good if you would
join us and help us in this matter.

Installing them by default (HTML and PDF) would be a good start. Having
a documentation pattern would be a nice addition. Having a desktop icon
providing access to the manuals as well as a menu entry in the main
menu would make people aware of the documentation. Putting some work
into the KDE and GNOME help centres to make them do what they are
supposed to do would be another milestone ;-).

Here is where you can find the official openSUSE documentation:


      * opensuse-manuals_en
      * opensuse-apparmor-quick_en-pdf (openSUSE AppArmor Quick Start)
      * opensuse-apps_en-pdf (openSUSE Application Guide)
      * opensuse-gnomequick_en-pdf (openSUSE GNOME Quickstart
      * opensuse-gnomeuser_en-pdf (openSUSE GNOME User Guide
      * opensuse-installquick_en-pdf (openSUSE Installation Quick Start)
      * opensuse-kdequick_en-pdf (openSUSE KDE Quickstart)
      * opensuse-kdeuser_en-pdf (openSUSE KDE User Guide)
      * opensuse-reference_en-pdf (openSUSE Reference)
      * opensuse-security_en-pdf (openSUSE Security Guide)

OK, having had my rant here is my answer to Javier's initial mail and
to other comments/proposals:


> in
> pdf format ready to be downloaded, printed and even ready to be sent
> to a publishing company is a good idea.

We currently provide color PDFs, HTML, and ePUB. We can also provide a
ready-to-print PDF, neatly formatted ASCII, and MediaWiki text
(basic functionality, stylesheets could need some work).

The openSUSE documentation is created in XML (a subset of DocBook),
because this is the only format that gives us the flexibility to
produce almost every output format we currently need or will need in
the future (we only recently dded ePUB).

All openSUSE manuals are licensed under the GFDL.

> ******************************
> The openSUSE Handbook
> ******************************
> Introduction
> - What's the openSUSE project?
> - What's openSUSE?

Currently not covered in our manuals, but since the text is already
available in the wiki, adding it should be fairly easy.
> Installing openSUSE
> - Different types of install methods

Covered to some extend in the reference guide, if there is need this
could be extended. The default installation path is also described as a
step-by-step guide with screenshots in the Installation Quick Start.

> - AutoYaST

Currently not part of the openSUSE manuals, but documentation exists
for SLE and could be added. So far this hasn't been asked for.

> Installing applications
> - Using 1-click
> - Using YaST
> - Using zypper

All covered in the reference and Start-Up Guides

> Desktop environments
> - An introduction to DEs (KDE, GNOME, XFCE, LXDE).

* Gnome Quick Start
* Gnome Manual
* KDE Quick Start
* KDE Manual
* Application Guide

XFCE and LXDE currently not available, this would need help from the
community. In case of XFCE I would vote against writing our own manuals
because the documentation provided by XFCE itself is very good. Maybe a
quickstart (I probably could do it myself since I am an XFCE user).

I do not know what's the status of the LXDE documentation, though.

> - Enabling proprietary drivers (ATI, NVIDIA)

this seems to change with every release and always implies last minute
changes - this is definitely a topic for the wiki, since a manual would
probably already be outdated on release date

> - Multimedia

Covered in the KDE, Gnome and Application Guides

> - Printing

Covered in the Start-Up and (all the gory details) the Reference Guide

> - Games

Currently not covered. To be honest, I do not see the need to document
them (it would probably just be copying the existing documentation)

> System administration
> - Introduction to the command line
> - Networking
> - Security
> - Storage
> - Virtualization
> - Keeping openSUSE up-to-date
> - Upgrading openSUSE

Everything is covered except Virtualization and Storage. Both topics
are covered in SLES, so documentation is available in principle. So
far, Product Management hasn't seen a need to include them with

> Servers
> - Apache and lighttpd

Apache is covered in detail, lightttpd not. IMHO it is sufficient to
document one of the two.

> - MySQL and PostgreSQL
> - Postfix
> - BIND
> - Samba

All not covered. The reason for this is: Very good books each
with several hundred pages exist on the market. We will not be able to
cover those topics to the same extend as the books do. What we could do
is to provide a basic introduction and that would not fit these complex

> - CUPS

Covered in the Reference Guide

> etc

We also have a security Guide.

> Other openSUSE Technologies
> - Build Service
> - KIWI

Both projects are under heavy development and are constantly changing.
Documentation has to be written and maintained by the projects
themselves, otherwise you will just produce outdated manuals that will
help nobody. ;-)

> - SUSE Studio

We have just finished writing a Studio guide (released under GFDL). It
will be published under any day soon.
> Drawbacks:
> We would need to update some of its contents for each openSUSE
> release. It needs more than two people to make it happen ;-)

It's more than that. the complete manual needs to be _reviewed_ and some
of it's content has to be updated. The updated parts need to be
proofread (content-wise and language-wise).
The biggest challenge is, that all this has to be finished two weeks
before release date. otherwise the manuals will not make it into the
distribution. If the manuals are going to be translated (currently some
guides are translated into German), they have to be ready 5 weeks
before release date... .
> On the other hand, I think that the handbook would make openSUSE more
> "visible" and a bit more "ready to use."
> Comments and suggestions are welcome! :-)

Use what is already there and help to improve it ;-).

Three years ago we (the Nuremberg documentation team) launched a
project called Lessons for Lizards. The idea was to have a cookbook
style manual covering all sorts of topics that don't make the official
manuals. We provided the complete infrastructure (SVN, mailinglist,
build environment, support, etc.) and a skeleton book that already
included a few articles and a structure. The project was announced on
different channels including a speech of mine at FOSDEM.

We had a _single_ contributor (thanks a lot Alexey!) from the
community and so the project slowly died... . (although it could be
revived very quickly).


Frank Sundermeyer, Technical Writer, Documentation
SUSE Linux Products GmbH, Maxfeldstr. 5, D-90409 Nuernberg
Tel: +49-911-74053-0, Fax: +49-911-7417755;
SUSE Linux Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg)
"Reality is always controlled by the people who are most insane" Dogbert
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]