How to contribute: openSUSE Documentation

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

How to contribute: openSUSE Documentation

Juergen Weigert-2
Hi there!

Last week a discussion started on opensuse-marketing about creating an
openSUSE manual:

http://lists.opensuse.org/opensuse-marketing/2010-09/msg00259.html

While this is a cool idea, it turned out that many people are unaware of the
existing openSUSE documentation or do not know how to contribute.  Being
responsible for the openSUSE documentation, I would like to shine a light on
this ;-) :

Table of contents (beware, lengthy posting):

1. Contributing
 1.1 Getting in touch with the SUSE Documentation Team
 1.2 Reporting Documentation Bugs or Suggesting Adjustments
 1.3 Translating Manuals
 1.4 Contributing new Chapters or Books
 1.5 Contributing to the Build Environment (susedoc)

2. Outlook: What's in the Pipeline
 2.1 Publishing the Book Sources
 2.2 Re-writing the Build Environment
 2.3 openSUSE BookBuilder

3. List of openSUSE Manuals


###################
# 1. Contributing #
###################

Currently the openSUSE documentation (listed below under 3.) is
maintained mostly within Novell by the SUSE Documentation Team
(http://en.opensuse.org/openSUSE:Documentation_team). The discussion on
opensuse-marketing has shown that people are interested in contributing to
this documentation--a fact that we really welcome!

Our manuals are written in NovDoc XML, a simplified subset of DocBook
(http://www.docbook.org/). The XML sources for the manuals are hosted on an SVN
server. Generating books from the XML sources is done with the susedoc build
environment, which is developed and maintained by the team as
well. This build environment includes _everything_ to build books from DocBook
or NovDoc and is shipped with openSUSE (package: susedoc, license: GPL).

You may also want to point us to ommissions, corrections,
or even to ready articles (wiki, txt, pdf, whatever) that could be
merged or referenced. Let us not get into a struggle about correct
or wrong tools. I really like the original idea of creating a commuity
driven openSUSE book.
We are already looking into ways how to interconnect wiki and/or
openoffice with docbook. Ideas welcome!


1.1 Getting in touch with the SUSE Documentation Team
-----------------------------------------------------
Reaching out to us is pretty easy - either subscribe to the opensuse-doc
mailinglist (http://en.opensuse.org/Mailing_lists#Subscribing) or join the
#opensuse-doc IRC channel on freenode.
If you have typos, questions, suggestions or simply want to say hello,
these are the places to go.

You can also meet us in person at the openSUSE conference in
Nuremberg this week. There will be a talk about one of our latest doc
projects, the openSUSE Book Builder (see 2.3 below or refer to
http://conference.opensuse.org/indico//contributionDisplay.py?contribId=71&confId=0).
We would be glad to see you there!


1.2 Reporting Documentation Bugs or Suggesting Adjustments
----------------------------------------------------------
Currently, two feedback channels are available if you have corrections or
enhancements for us:

- File a bug report (or an enhancement request) against the
  Documentation component for the respective product.

Or, much easier:

- Use the doc comment system:

Go to http://www.novell.com/documentation/opensuse113/ where the openSUSE 11.3
documentation is hosted. Click on a manual title and navigate to the page
where you have spotted an error/would like to suggest adjustments. Scroll to
the bottom of that page and click on "Add comment". Insert your comment. If
you are interested in getting feedback, provide your name and email address.

Your comment is directly routed to our team, so we can take care of it.


1.3 Translating Manuals
-----------------------
If you are interested in translating our manuals, we can provide the necessary
infrastructure for you. Currently the Russian translation team already uses
our SVN repository on berliOS to translate the openSUSE 11.3 manuals.


1.4 Contributing new Chapters or Books
--------------------------------------
If you would like to contribute larger amounts of contents (chapters,
sections, etc.), please get in touch with us (see above), and let us know what
you like to contribute. Don't worry, you _DON'T_ have to know XML, susedoc, or
the likes - that is something we can take care of ;-).


1.5 Contributing to the Build Environment (susedoc)
---------------------------------------------------
susedoc is publicly hosted at
https://developer.berlios.de/projects/opensuse-docmaker/ and can be checked
out anonymously. Patches are welcome! If you are interested in contributing
more than an occasional patch, you can get full access to the project.



######################################
# 2. Outlook: What's in the Pipeline #
######################################

The SUSE documentation has a few more projects in the pipeline. First and
foremost we are working on making it easier for you to contribute. Second we
have have planned two major software projects.

2.1 Publishing the Book Sources
-------------------------------
The XML sources for our manuals are hosted on a Novell internal SVN
server. We are currently in the process of moving them to a public SVN at
berliOS, where they will be available for anonymous checkout. Document
maintainers will get write access.
As a first step, the SUSE Studio documentation and the openSUSE Documentation
Style Guide are hosted at
https://developer.berlios.de/projects/opensuse-doc/
More is to come very soon.

We can also provide an infrastructure for manual translations on that server
- in fact our Russian translators already make use of it.


2.2 Re-writing the Build Environment
------------------------------------
Our build environment (susedoc) currently is a mixture of tools using make,
bash, python and perl. Although this tool collections works very well, we
would like to consolidate it in order to make future enhancements easier. We
have started to write a central docmaker library in perl and python which
should provide  everything that is needed to manage, monitor and build books
from XML sources. Development of this library is in a very early state - if
you are interested in helping us to develop it, get in contact with us. The
sources are available from
http://svn.berlios.de/wsvn/opensuse-docmaker/trunk/lib/


2.3 openSUSE BookBuilder
------------------------
In short, the openSUSE BookBuilder is a library utilizing susedoc to
automatically build books from XML sources. Added is a web application that
serves as a virtual library. See
http://conference.opensuse.org/indico//contributionDisplay.py?contribId=71&confId=0
for a more detailed description. If you are interested in that project, come
to the talk at the openSUSE conference or contact me directly.



###############################
# 3. List of openSUSE Manuals #
###############################

openSUSE comes with with a lot of manuals in HTML and PDF format with a current
page count of almost 2000 pages. Not all of them are shipped in the box.
The HTML version of all manuals can be installed with the package
opensuse-manuals_en.
http://en.opensuse.org/openSUSE:Documentation_team#List_of_Manuals
http://en.opensuse.org/SDB:Official_documentation 

ePUB versions can be downloaded from
http://community.opensuse.org/ebooks/ebooks113/


3.1 Startup Guide
-----------------
Guides you through the installation and basic configuration of your
system. For newcomers, the manual also introduces basic Linux concepts such as
the file system, the user concept and access permissions and gives an overview
of the features openSUSE offers to support mobile computing. Provides
help and advice in troubleshooting.
The Startup Guide is ca. 200 pages and is found in the openSUSE box.

3.2 Reference Guide
-------------------
Gives you a general understanding of openSUSE and covers advanced system
administration tasks. It is intended mainly for system administrators and home
users with basic system administration knowledge. It provides detailed
information about advanced deployment scenarios, administration of your
system, the interaction of key system components and the set-up of various
network and file services openSUSE offers.

3.3 GNOME User Guide
--------------------
Introduces the GNOME desktop of openSUSE. It guides you through using and
configuring the desktop and helps you perform key tasks. It is intended mainly
for end users who want to make efficient use of GNOME desktop as their default
desktop.

3.4 GNOME Quick Start
---------------------
Gives a short introduction to the GNOME desktop and some key applications
running on it.

3.5 KDE User Guide
------------------
Introduces the KDE desktop of openSUSE. It guides you through using and
configuring the desktop and helps you perform key tasks. It is intended mainly
for users who want to make efficient use of KDE as their default desktop.

3.6 KDE Quick Start
-------------------
Gives a short introduction to the KDE desktop and some key applications
running on it.

3.7 Application Guide
---------------------
Learn how to use and configure key desktop applications on openSUSE. This
guide introduces browsers and e-mail clients as well as office applications
and collaboration tools. It also covers graphics and multimedia applications.

3.8 Security Guide
------------------
Introduces basic concepts of system security, covering both local and network
security aspects. Shows how to make use of the product inherent security
software like AppArmor (which lets you specify per program which files the
program may read, write, and execute) or the auditing system that reliably
collects information about any security-relevant events.

3.9 Installation Quick Start
----------------------------
Lists the system requirements and guides you step-by-step through the
installation of openSUSE from DVD.

3.10 AppArmor QUick Start
-------------------------
Helps you understand the main concepts behind AppArmor.


Thanks to Frank, Tanja, Tom for compiling this writeup,
(shame on me for messing it up).

        cheers,
                JW-

--
 o \  Juergen Weigert  paint it green!    __/ _=======.=======_
<V> | [hidden email]       back to ascii!  __/        _---|____________\/
 \  | 0911 74053-508                __/          (____/            /\
(/) | _____________________________/              _/ \_ vim:set sw=2 wm=8
SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg)
"You are trying to use packages from project 'openSUSE:11.3'.
 Note that malicious packages can compromise your system."

--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How to contribute: openSUSE Documentation

Alexey Eromenko
There is already such project exist for openSUSE since 10.3.

It is called: "Lessons for Lizards". Google for it.

-Technologov
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [opensuse-project] How to contribute: openSUSE Documentation

Juergen Weigert-2
In reply to this post by Juergen Weigert-2
On Oct 18, 10 18:00:39 +0200, Freek de Kruijf wrote:
> Op maandag 18 oktober 2010 17:07:47 schreef Juergen Weigert:
>
> This information should be in the wiki in separate pages, but with links to it
> from Portal:Documentation and Portal:How_to_participate and Portal:Teams

Right you are! Thanks for those pointers.
I've taken the liberty and added my team to the portals.
(And chopped the contents into 3 parts.)

        cheers,
                JW-

--
 o \  Juergen Weigert  paint it green!    __/ _=======.=======_
<V> | [hidden email]       back to ascii!  __/        _---|____________\/
 \  | 0911 74053-508                __/          (____/            /\
(/) | _____________________________/              _/ \_ vim:set sw=2 wm=8
SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg)
"You are trying to use packages from project 'openSUSE:11.3'.
 Note that malicious packages can compromise your system."

--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: [opensuse-project] How to contribute: openSUSE Documentation

Jos Poortvliet-2
On 2010-10-18 Juergen wrote:

> On Oct 18, 10 18:00:39 +0200, Freek de Kruijf wrote:
> > Op maandag 18 oktober 2010 17:07:47 schreef Juergen Weigert:
> >
> > This information should be in the wiki in separate pages, but with links
> > to it from Portal:Documentation and Portal:How_to_participate and
> > Portal:Teams
>
> Right you are! Thanks for those pointers.
> I've taken the liberty and added my team to the portals.
> (And chopped the contents into 3 parts.)
+1 it can help people find your team...

>         cheers,
>                 JW-



signature.asc (205 bytes) Download Attachment