Home Wiki > openSUSE:Documentation Contribute
Sign up | Login

openSUSE:Documentation Contribute

tagline: From openSUSE

Contribute to the openSUSE manuals.

How to Contribute

Formerly the openSUSE documentation was maintained mostly within Novell by the SUSE Documentation Team.

Starting from that background, we publish the current state of drafts at [1] and offer an interactive commenting and editing for our existing books at [2].

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. Activedoc is easy, no XML, no docbook...

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/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