For publishing large documentation projects, DocBook is the ideal framework. It consists of a language (DocBook XML) and a set of stylesheets to translate this language into different output formats such as HTML, PDF, and EPUB.

The stylesheets define the layout you want to apply when transforming the XML sources into output formats. For SUSE documentation, we wrote our own XSLT stylesheets to ensure the corporate design is properly reflected.

The language DocBook XML is based on the eXtensible Markup Language (XML) and defines the content in a semantic way through elements like in HTML. DocBook itself is written as a schema that defines the element names and the content and where they can appear. The DocBook schema is used to fulfill two tasks: guided editing and validation.

Guided editing is done via an XML editor (such as oXygen, Vim or Emacs). The editor reads in the DocBook schema and suggests which elements are allowed in the current context. Validation gives hints about structural errors in an XML document; this could, for example, be a missing element.

Similar products often share a considerable amount of features and differ in details only. If you want to generate multiple documentation variants from your XML files, you can do so with the help of conditional text – or profiling, as it is called in DocBook. For example, you can profile certain parts of your XML texts for different (processor) architectures, operating systems, vendors or target groups.

While learning DocBook might seem cumbersome at first sight, it comes with many unique advantages. Among others, it is ideal for the modular structures of complex documentation, it provides profiling, and you can generate many different output formats from the same XML sources.

AsciiDoc – An alternative for easy contribution

Documentation projects are getting more complex and are more and more reliant on contributions from external experts, who don’t have a technical writing background. For those projects and contributors, AsciiDoc offers a serious alternative. AsciiDoc belongs to the lightweight markup languages and provides a plain text documentation syntax and processor. It is not as modular and extensive as DocBook, but it is easy to understand and to use.

One of the biggest advantages of using AsciiDoc as a source for documentation is its seamless integration with GitHub. GitHub not only renders AsciiDoc sources, but also allows to edit them directly in the Web interface. This fits nicely with GitHub‘s Web-based pull request workflow: You edit the document online, click a button, and someone else (usually the repository owner) can review and integrate the change. All you need is a free GitHub account (which many developers and technical experts already have). This improves the contribution flow for external contributors.

Summary

Each document format comes with some advantages and disadvantages. As an example, tables are complex to create with DocBook XML, but the same holds true for nested lists in AsciiDoc(tor). We are flexible, therefore our toolchain supports both DocBook and AsciiDoc. But of course, we do not expect at all from contributors to provide the documentation team with complex XML tables or similar. Every contributor is free to write their documents with the tool of choice, and the documentation team converts them accordingly.

At the end, what really counts is that contribution is made easy for you. No matter in which format you want to provide your content to us: Word or OpenOffice documents, pure text files, PDFs, Ascii or anything else: WE JUST TAKE THEM ALL and publish your contribution.

Disclaimer: The text at hand has not been reviewed by a native speaker. If you find typos or language mistakes, please send them to me (meike.chabowski@suse.com) – or if you like them, just keep them and feed them. ?