From 0 to “Hit Publish!”: How We Create SUSE Documentation

The following article has been contributed by Stefan Knorr, Technical Writer at the SUSE Documentation Team.

On various occasions over the past year and a half my colleagues Meike, Dima, and Carla have already mentioned the not-so-secret sauce we use to create our documentation on this blog. While good information may be the main content of it, there are tools and processes too, and of course personal dedication (ha: that last bit was really sappy, and it’s all downhill from here!).

Photo by Dmitri Popov on Unsplash

Our main software tool is called DAPS. Well that, and there’s also our text editors. But, since among the thirteen of us, we probably have sixteen different text editors, spanning the range between nano (admittedly, for commit messages only) and Emacs, between Geany and oXygen, that would be a post in and of itself. Nevermind the ensuing in-fighting here at the office over the topic. So, let’s discuss something less controversial instead: DAPS. That acronym stands for DocBook Authoring and Publishing Suite.

I still haven’t explained what it does, but fret not! Here we go: DAPS takes our documentation sources (which are in a format called DocBook XML) and transforms them into output that actual humans (that is, not just tech writers such as myself) may actually want to consume. There’s the two heavy-hitter output formats HTML and PDF, and there’s also-rans such as EPUB and plain-text.

And of course, just having output is not enough: We want it to work well for our readers, too! So, not only do we take care to choose the right layout and font size and remove spelling errors, we also try to not confuse you with unchecked terminology or badly structured documents. And, because some of you’d probably rather read our documentation in a language other than English, DAPS needs to integrate with localization processes too. There we go: From all those requirements, you might now expect DAPS to be a complicated monster of a tool — in actuality, while it would be wrong to describe it as svelte (it does have a few dependencies), it is indeed easy to use. Once you have developed even a passing familiarity with command-line interfaces, that is.

While DAPS is completely the invention of my colleague Frank, that does not mean he wrote all of the components himself. By the power of open-source, it binds together tools from various communities. There’s the DocBook XSL Stylesheets, various XML tools (such as xmllint, xsltproc, and optionally Saxon), image tools, and Apache FOP which we use to render PDFs. It also integrates checkers for spelling, style, and URLs as well as EPUB tooling and image converters (we [ab]use Inkscape for that purpose, in fact).

You might remember that the title promised to take you from 0 to “Hit Publish!,” but all you learned so far is that we have a tool that does it all — all told, not too far from the truth — except we still have to feed it input. Getting input needs some kind of research, and since typing it all up in the end is easy, researching turns out to be a large part of our everyday work.

Part of researching a topic unsurprisingly is asking developers. Another part that makes this job rather more interesting than your average tech writing position is that we actually get to install and test most of the functionality we write about. Sometimes, we find bugs too!

When the researching part is completed to a sufficient degree, we will start to write, and make screenshots. The XML resulting from that must conform to our custom restricted set of DocBook 5 which is called GeekoDoc. To check whether it does conform (and here comes your first command snippet), there’s DAPS’s validation function:

daps -d DC-my-book validate

What’s with that DC something or other there?, I hear you ask. Well, I need to back up a bit again: DocBook lets you define all the content of your book. Using XIncludes in DocBook, you can also modularize content to some degree, so not everyone needs to work on the same huge file. DocBook’s “profiling” functionality even allows you to define parts of the document that you want to remove in some editions of the document. (Ever noticed that our SUSE Linux Enterprise Server and SUSE Linux Enterprise Desktops guides look very similar on their faces but their content differs quite a bit? Yep, those are created from different variants of the same source.)

But what pure DocBook misses is a way to permanently define some options for your document, such as what edition of the document to actually create. We could append this information to the DAPS command line. However, putting that information into a DC (or Doc Config) file is much easier and saves a lot of time the next time you or someone else needs the same document configuration. DC files also contain other information, such as what branding to use, which RELAX NG schema or DTD to validate with, or special parameters for the XSL stylesheets.

If the validate command does not check out, you have the honor of finding where you went wrong. DAPS makes it easier by printing a file name and line for the error, but XML error messages can be cryptic anyhow. But let’s not assume an error — you’re a good writer, you’ve picked a good editor, and it will all go fine.

Next, you might want to see your document. Of course, with DocBook, we are using semantic markup, that is, marking up in terms of content and not in terms of presentation, and that is great. But you’ll still occasionally want to verify that your documentation looks intelligible when you see it in the flesh too. Hence, let’s create an PDF (and from this, you can guess how creating HTML or EPUB output works):

daps -d DC-my-book pdf

Over time, you will develop a feel for how elements will look together in your layout. Then you may need to preview the document less.

When you are done writing, there is proofing. To check spelling, DAPS has the spellcheck command, to create an overview of stylistic and terminology issues, use the stylecheck command (note that you need to install DAPS from the OBS repository Documentation:Tools to use the latter). Finally, DAPS’s checklink will make sure that the URLs in your document don’t just go to 404 error pages. At this point, you have used all the automatic proofing options that DAPS allows for.

The most valuable feedback, however, you will still receive from humans. At SUSE, we pride ourselves on having the kindest co-workers, so that is who I would ask next. (By the way, if that sounds intriguing… hurry on over to the Jobs page.)

And that already concludes our little journey through the Nucle^Wdoc team, because finally, there is a simple:

daps -d DC-my-book online-docs

This will create all the documents in all (well, most) of the output formats that we use on our SUSE documentation webpage. After which we can ask our Web specialist Arul to publish the documentation on the server. That’s it.