Three astonishing things I learned during my first eight weeks in the amazing and _Sensational SUSE Documentation Team_

You might or might not have heard it yet: I just moved from Marketing to R&D because I was offered an appealing new role in the _Sensational SUSE Documentation team_ (this is how our team lead Markus Feilner calls the team since his first day at SUSE). I started my new journey about eight weeks ago. And these first eight weeks were really eye-opening for me. Here are my three main takeaways about documentation and the SUSE team, which I thought to share with you:

1) Documentation is underestimated

Documentation? Of software?

It’s automatically delivered with the product. Or it somehow plops out of the software code. You really think so? Well, no single deployment or admin guide, quick start or best practices paper just falls like manna from heaven. Every little piece of documentation is preceded by hours and hours of research, discussions, tests, structuring, thinking, writing, revisions, editing, etc. And after you have delivered a first draft, you – or the reviewers – discover that you need to restructure, retest and rewrite what you had written so far to provide rock-solid information for our customers.

Are you among those who say, “I don’t really need documentation”? Just be honest with yourself. When you buy a new bookshelf, and you get delivered a bunch of boards, bolts and dowels, and you don’t know where to start with this “puzzle”, what you are doing? You look up the product description and the assembly instructions. The same is valid for software. Normally, you should check out your deployment guide before you start your installation or, at least, while you are installing your software. If you didn’t, what are you doing when you get stuck? You’ll probably curse first, and after that you’ll search the right documentation guide, and you’ll follow the instructions.

In my view, documentation is an essential part of a product – above all when it comes to software. I would even go further and argue software documentation is not just a “nice to have” but a “must have” component of an application or software solution. Most software tools only become useable thanks to detailed documentation. Unfortunately, this opinion is not necessarily widespread. To the contrary, I recently heard people discussing documentation as being just a “cost factor” not delivering any “ROI”. The general value of documentation is definitely underestimated.

Most products are not usable without good documentation, especially, software products suffer from missing or poor documentation. I am sure you’ve faced such situations often enough in your private life. But if you work in an IT department and you are responsible for a functioning environment and smooth processes, this impacts your daily work and eventually even the success of your business. Documentation makes information easily accessible, helps new users learn quickly, simplifies the product and helps cut administration and support costs.

So don’t tell me documentation is not important.

2) Multi-talented team members  

Now, where do you think all the information for the single pieces of software comes from? I had always thought that my documentation colleagues got all of their input from the original software developers, partly in written form, partly via interviews, and that they “only need to write it down in an understandable way.” But I quickly learned: That would be the case in an ideal world. Reality is different.

When you work in documentation, you are not “just a technical writer” – at least not at SUSE. I am completely amazed by the skills of my colleagues. I have known most of them for many, many years, but I had no clue how talented every single one of them is. (By the way: don´t tell them they are talented; they will vehemently deny it!). I bet that each of them could do the job of a software engineer or a system administrator—because of these premises:

• Software development has tight schedules. Developers are under pressure to deliver their sections of software code in time; that’s their first priority. Developers normally love to write code, but not necessarily text. Most developers are geniuses in writing their code, but not necessarily in explaining it.
• Also, have you ever reflected on the fact that ready-to-use documentation usually is delivered in parallel with the software product and in several different languages? What does this mean? All of the essential guides, quick starts and how-to’s need to be written and ready for translation at a minimum 6-8 weeks before the general availability of a product.
• My colleagues in the documentation team had to learn how to deal with the somehow comprehensible but still cumbersome lack of information flow. And they made a virtue out of necessity. They started to download the software code still under development; they set up their own virtual machines; and they installed the work-in-progress products themselves.

Today, this is their normal procedure. As you surely can imagine, often it’s not an easy task, with just partly ready-to-use software. But they have become real experts in installing and getting up and running semi-finished software products, understanding complex technical context, finding bugs, working on turnarounds and even in writing their own software tools and pieces of code, to help them reach their goal of providing excellent documentation.

I would say they are all generalists, but each of them also has his or her area of deep expertise – Frank Sundermeyer and Tanja Roth, for example, can tell you a great deal about OpenStack and Cloud. Tanja and Thomas Schraitle are the gurus for the High Availability Extension. Karl Eichwalder knows SUSE Manager inside out. Stefan Knorr is on top of SUSE Linux Enterprise Server for SAP Applications. Tomáš Bažant in Prague is our valued expert for SUSE Enterprise Storage, Christoph Wickert and our trainee Fabian Vogt just joined the team two weeks ago but both are so skilled already that it is just a matter of “hours” until they pick their area of expertise, and our team lead Markus Feilner is our highly creative “williwaw” and “presentationator”. (You will hear more about all of them during the next weeks and months.)

No matter what kind of problem I had (and still have) during the installation of my new working infrastructure, or whatever question arises with regard to one of new tools I have to operate to create a piece of documentation, I am always getting expert advice and help from them. The same holds true in general for the collaborative spirit within the team. For every “challenge”, they find a solution together, even if the answer is “Let me quickly write a script to resolve your issue.”

This is true proficiency.

3) A highly sophisticated workflow with well thought-out processes

Speaking about tools or workflow for documentation, I’d never expected to find such a highly organized working environment. I assume, just like me, not many people give a thought to the workflow how our documentation is created. Let me give you a high-level overview of our infrastructure:

• How do we get requests and input for new product documentation or feedback on existing documentation? Most request reach us through the following three channels:
  • FATE is the Feature and Requirements Management System for our products. Through this tool, we get most of new documentation requests.
  • Bugzilla is the bug tracking system used for our products. Via this tool, we also receive new documentation requests as well as bug reports for the enhancement of our documentation.
  • Doc User Comments is a feedback system attached to the (multi-page) HTML versions of the product documentation that is available at http://www.suse.com/documentation. You can leave your comments on each webpage.
• For task tracking and project management, we use web-based tools, to ensure none of the request from FATE, Bugzilla or other channels gets lost, and we keep to our schedules.
• For the actual writing, editing and publishing of our documentation, we have a single-source publishing process, based on the following tools:
  • DocBook XML is the main format we are writing in. It 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 used in our XML editor. Each team member has free choice which editor to use, be it a graphical editor or a command-line editor (by the way, the variety of editors is huge and ranges from Oxygen and Emacs, to Sublime Text, Vim, and jEdit, to many many others). The editor reads in the DocBook schema and suggests which elements are allowed in the current context. Validation gives us hints about structural errors in an XML document; this could, for example, be a missing element.
  • I had to learn DocBook XML from scratch, but I am already a fan of it.  It is ideal for the modular structures of documentation, and even if you have to invest a bit more time for your initial document, you benefit later because updates or changes are easy to execute. If you want to learn more about DocBook XML, I recommend you read the DocBook XML guide written by my colleague Thomas Schraitle.  (German only), or you have a look at http://docbook.org/.
  • DocBook Authoring and Publishing Suite (DAPS)  is a command-line tool we use to generate output formats (like HTML or PDF) from the XML sources. We provide most of our documentation as HTML, single HTML, PDF and ePub. DAPS also allows us to manage the key tasks related to writing and editing, like collecting the files that should go to translation or running additional tools like a spell checker and our style checker. This helpful tool was invented by my colleague Frank Sundermeyer.
  • The XSLT Stylesheets  define the layout we use when transforming the XML sources into output formats with DAPS. Our stylesheets have been written by Thomas Schraitle and Stefan Knorr.
  • We also use a style checker program – also developed by Stefan – to ensure we keep to our own language and structure specification.
  • DocManager is a command-line tool to add and track meta information about the files that belong to a documentation project. It stores the information as XML structures in the DocBook files.
  • Git is our main version control system for our product documentation. We use GitHub as a hosting server for our sources. GitFlow is a collection of shell scripts that makes the daily work with Git easier. As far as I can see, Git is the perfect collaboration and versioning tool for our purposes.

Of course many other steps from peer and expert reviews, to translation, to packaging and up to publishing on our SUSE Documentation portal are involved in creating the all-around carefree package of documentation. Going into more detail here would probably be too much. But I hope you get an idea of the sophisticated infrastructure and the processes designed down to the last detail to ensure the effective functioning and high quality of our documentation.

At least I am deeply impressed, after my first eight weeks as a part of the SUSE documentation team, by the concentrated experience and knowledge, cordiality and cooperativeness of my team members. More to come …