On Wed, 29 Sep 2010 20:27:11 +0200 Javier Llorente wrote: Hi, (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: Web: http://en.opensuse.org/SDB:Official_documentation System: Packages: HTML: * opensuse-manuals_en PDF: * 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: See

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

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

- 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 www.novell.com/documentation 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). -- Regards Frank Frank Sundermeyer, Technical Writer, Documentation SUSE Linux Products GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.opensuse.org/ 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: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org