openSUSE:Documentation Contribute

tagline: From openSUSE

Contents 1 How to Contribute 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 Publishing the Book Sources 1.6 Re-writing the Build Environment 1.7 SVN Structure 1.8 Feedback via the official channels

How to Contribute

Currently the openSUSE documentation is maintained mostly within Novell by the SUSE Documentation Team. The discussion on opensuse-marketing has shown that people are interested in contributing to this documentation—a fact that we really welcome! For short article style documentation just head over to http://activedoc.opensuse.org and start contributing there. This is our big melting pot, where we collect material that may sooner or later end up in 'the manuals', the official documentation.

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 DAPS (DocBook Authoring and Publishing Suite); for more information about daps, see http://daps.sf.net. This build environment includes everything to build books from DocBook or NovDoc and is shipped with openSUSE (package: daps).

Let us not get into a struggle about correct or wrong tools. We really like the original idea of creating a community driven openSUSE book. And we are already looking into ways how to interconnect Wiki and/or OpenOffice with DocBook. Ideas welcome!

A tribute to our EMACS users

Getting in touch with the SUSE Documentation Team

Reaching out to us is pretty easy—either subscribe to the opensuse-doc mailinglist 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.

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.

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 to translate the openSUSE 11.3 manuals.

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

In case you are curious to write in XML, have a look at the video at flow3.typo3.org. Although it relates to Typo3, it is nevertheless very useful as it shows how you can work in XML without too much pain.

Publishing the Book Sources

The XML sources for our manuals are hosted on https://svn.opensuse.org server. Document maintainers will get write access.

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

Re-writing the Build Environment

Our build environment (DAPS) 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. The sources are available from https://daps.sf.net.

SVN Structure

The structure of our SVN server looks like this:

• trunk/documents
  Each subdirectory contains a product. It is possible to just check out only those subdirectories which you are interested in. So you don't have to check out everything. :)
  • trunk/documents/distribution
    Contains our complete openSUSE distribution, including SLES and SLED. This subdirectory is the biggest one. The reason for this is we share a lot of text between openSUSE and SLE{S,D}. Usually it contains the languages in it.
  • trunk/documents/distribution/ha
    For administrators who like to know something about our high availability world
  • trunk/documents/distribution/slepos
    Contains the SLEPOS guide and a configuration manual for the SUSE Linux Enterprise Point of Service
  • trunk/documents/distribution/smt
    Gives you an overview about our SUSE Lifecycle Management Server
  • trunk/documents/distribution/studio
    Contains an Quick start, a user, and an admin guide about SUSE Studio Onsite
  • trunk/documents/styleguide
    Like some coding styles for programmers, we have also some guidelines how we create our documents. We use the styleguide to clarify how to make our docs consistent and hopefully easy to read.
  • trunk/documents/webyast
    YaST over Web
• trunk/tools
  Includes some important documentation tools:
  • trunk/tools/daps
    The DocBook Authoring and Publishing System, our newest build machineary which creates PDF, HTML, EPUB, or text. Contains the sources and documentation how to use it. This directory is for interested developers. Users should install the daps RPM package from the Documentation:Tools repository.
  • trunk/tools/docmaker
    Our former build machinery, known also as susedoc. This is considered deprecated.
  • trunk/tools/obb
    If you've visited the talk from Frank and Tomas, this subdirectory contains the Perl sources for the openSUSE Book Builder.
  • trunk/tools/susedoc_buildbook
    Some scripts to create RPM packages from our sources. Mostly the playground for Karl.

Feedback via the official channels

Now, if you don't want to write for us or let us suck your brains out ;), there are still things you can do to support your SUSE Doku-Wichtl:

• File a bug report if you find any problems in the manuals (how to report bugs). Use the component "Documentation".
• opensuse-doc@opensuse.org - Tell us what we can do better in our manuals and maybe how. Provide feedback about our documentation system and help us to ameliorate it..
  Subscribe - Unsubscribe - Help - Archives