Document formats – There is choice

Share
Share

Did you know that everyone can contribute to good and even better SUSE documentation?

For example, in the real spirit of open source, we invite all technical experts of the SUSE ecosystem to share their expertise and knowledge via a SUSE Best Practices document. The SUSE Best Practices are a series of documents that provide reliable technical information not covered with the SUSE product documentation and based on real-life scenarios. While the SUSE product documentation mainly guides through the installation and usage of a product, the SUSE Best Practices provide installation and implementation experiences. And while the SUSE product documentation is delivered in parallel with a new product or a next version, the SUSE Best Practices usually adhere to products already introduced to and established in the market.

But the SUSE Best Practices are not the only option to get involved. You can also contribute to or help enhance the existing product documentation. To do so, you can or submit a bug via Bugzilla, or edit the documentation sources in GitHub yourself. Usually, when I mention these options during conversations, I am asked “how” we write documentation at SUSE, means what tools we use to actually write our content.

Well, there are plenty of tools that can be used to create documentation texts, depending on the authors’ preference. For SUSE documentation, we currently work with two different document formats which are explained here a bit more in detail.

DocBook – The document format of choice

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

Share
(Visited 1 times, 1 visits today)
Meike Chabowski
288 views
Meike Chabowski

Meike Chabowski works as Documentation Strategist at SUSE. Before joining the SUSE Documentation team, she was Product Marketing Manager for Enterprise Linux Servers at SUSE, with a focus on Linux for Mainframes, Linux in Retail, and High Performance Computing. Prior to joining SUSE more than 20 years ago, Meike held marketing positions with several IT companies like defacto and Siemens, and was working as Assistant Professor for Mass Media. Meike holds a Master of Arts in Science of Mass Media and Theatre, as well as a Master of Arts in Education from University of Erlangen-Nuremberg/ Germany, and in Italian Literature and Language from University of Parma/Italy.