Not too long ago, mid of September, I was attending this great Documentation Conference, Write the Docs, which – like many other conferences this year – took place in beautiful Prague.

The WTD org team somehow decided that my session proposal “An Alien Looking From the Outside In – Main Take-Aways After a Year in Documentation” sounded funny. Thus, all of a sudden, I found myself speaking in front of an experienced crowd of technical writers, content experts, developers, UI designers, marketers, etc … And it was fun, because after the talk, I got several requests to provide my observations in the form of a blog article – so here you go!

Curious why I call myself “an Alien”? Some of you might know that I am coming from a completely different background: a humanistic one. I am a Master of Arts in IT(E) – means in Italian Literature & Language, Theater and Mass Media, and Education – but somehow ended up in REAL IT about 23 years ago. Most of my time I spent on the business part of the game, in Marketing. Until I moved to the R&D department and found a new home at the SUSE documentation team. I think, with this background, it is ok to call myself “An Alien” for certain purposes.

But now let’s jump into the “essentials” ….

Observation #1

Documentation? Of software?  It happens because a flash of inspiration regularly takes hold of you … Or 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 your customers.

Have you recently heard someone saying: “I don’t really need documentation”? Ask them to be honest with themselves! 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 holds true for software. Usually, 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.

But still, just recently at an open source conference, a guy I know for ages told me: “Documentation? No one reads it anyways”. And at SOAP! Conference in Krakow, another really cool content event, they spread stickers with this and similar “statements”.

Isn’t it a paradox? Everyone thinks writing good documentation is “easy”, but then nobody wants to write it? Everyone wants good documentation, but then they tell me nobody reads it? But if valuable documentation is missing, everyone complains “we could not fulfill our job because there was no documentation on how to do it.”

You heard me emphasizing this many times before: documentation is an essential part of a product – above all when it comes to software. Most software tools only become usable 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”. I even heard people saying documentation “should be outsourced”. But if you work in an IT department and you are responsible for a functioning environment and smooth processes, missing or poor documentation might impact your daily work and eventually even the success of your business.

So don’t tell me documentation is not important! Documentation still definitely is underestimated. And we need to change this.

Observation #2

Now, where do you think all the information for the single pieces of software comes from? I was always under the impression all input comes from the original software developers, and that my colleagues “only need to write it down in an understandable way.”

But I quickly learned: That would be the ideal world. Reality is different.

And reality initially let my hair stand on end.

When you work in documentation, you need to have SUPERPOWER. 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!).

Software development has tight schedules. Developers are under pressure, first priority is to deliver their code in time. They love to write code, but not necessarily text. To make things even more complicated, 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 ready for translation roughly 8-12 weeks before the product will generally be available.

My doc colleagues had to learn how to deal with the lack of information flow. And they made a virtue out of necessity. They started to download the still-in-development software code, set up their own virtual machines, installed the work-in-progress products themselves, and started to document “from own experience”.

Today, this is their normal procedure. They have become real experts in running semifinished 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.

The collaborative spirit within the team is huge. 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. And brings me to my observation number two:

Behind great documentation, there is usually an amazing team.

Observation #3

A few sentences earlier I mentioned “tools” for documentation. And I assume, just like me in former times, not many people give a thought to the workflow how documentation is created.

Honestly, I never had expected to find such a well thought-out, streamlined workflow. So what you see here is an overview of OUR workflow.  

Overstrained now 😆 ? Let me quickly explain our “infrastructure” and the different steps

It all starts with a documentation request. Requests usually reach us via three channels:

FATE, our internal Feature and Requirements Management System,

Bugzilla, the bug tracking system we use,

Doc User Comments, a feedback system attached to the HTML versions of the product documentation.

For task tracking and project management, we use Trello, to ensure none of the request from FATE, Bugzilla or other channels gets lost, and we keep to our schedules. In a next step, we create the infrastructure in Git, which is our standard version control system.

For the actual writing, editing and publishing of our documentation, we created a single-source publishing process, based on the following tools:

In parallel with the research work, we start to write the content in DocBook XML, our document format of choice. It is based on the eXtensible Markup Language abd It is ideal for the modular structures of our documentation. Guided editing is done via the XML editors. Each team member has free choice which editor to use. The variety of editors ranges from Oxygen and Emacs, to Sublime Text, Vim, jEdit, and many others.

To provide consistent documentation, we defined our document and writing style in our SUSE Style Guide. The Style Guide contains the structural overview for all manuals, naming conventions, rules regarding abbreviations, explanation of our tone and voice inside tech documentation, which elements of DocBook to use, the terminology, and many examples.

DocBook Authoring and Publishing Suite (DAPS) is a command-line tool we use to generate output formats 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.

The XSLT Stylesheets define the layout we use when transforming the XML sources into output formats with DAPS. The Style Checker program ensures 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.

During the entire writing and editing phase we are frequently building the document via DAPS. This helps us validate it for correct links, references, spelling etc. during the writing process. We build the document in all different output formats to ensure all looks good. We do proofs of the output ourselves.

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. But I assume you already got an idea of my third observation:

A streamlined workflow, with tools that function and processes that are carefully designed to support your daily work, makes things easier. And it is crucial in ensuring a high quality outcome.

Observation #4

Now, at least at SUSE, the documentation team is not the only team to write technical documents. Just as one example, there is our Technical Alliances team. These highly experienced colleagues work with our big Hardware and Software partners. They provide specific reference architecture documents, design papers, software implementation guides. And they have to cooperate on those papers with partners.

Currently they are writing their documents with different tools, which is often time-consuming and painful due to formatting issues. And they would love to focus on the content not on format. In addition, the Look & Feel of these documents is different from our official SUSE documentation. As they are not going through the documentation publishing process, they are not published on the official documentation webpage, and are made available only as PDF.

However, our customers and partners rightly view ALL technical documents published by SUSE as “SUSE Documentation”. Of course they don’t care which team wrote what. And hold the documentation team responsible for all updates and enhancements.

Luckily we found a solution: The Tech alliance team decided to standardize their technical documents via the documentation workflow and toolchain. This will happen in close collaboration between the teams.

And brings me to my fourth observation:

Standardizing the (process how to create) technical documents of your company usually entails a win-win situation for everyone – for the teams that deliver those additional technical papers, for the documentation team, but most importantly for your customers and partners.

Observation #5

The following pieces of wisdom not only hold true for documentation, but also for our engineers’ work in general: If you don’t talk about the great stuff you are doing, no-one else will do it for you. Make your work relevant. Spread the word about your accomplishments.

Regarding documentation, talk about the guides and manuals that have freshly been published. Use social media and blog articles. Try to find new channels, to make documentation more “catchy” and less boring – why not make a demo video, or a quick install in comic-form – just be creative. Let all those documentation disbelievers and backseat drivers know what important and great work you are doing. Proof them that documentation is an essential part of the product. Take constructive negative feedback from your users serious. Stay in communication with them. And if you get positive feedback for your work, don’t hide it either. So, my last observation for today is:

Make your work be visible, it does not hurt! In the contrary!

As to documentation, you’ll see: the voices that try to suggest that “no-one reads it anyways” or that documentation “could be outsourced” will soften and fall silent. And this is potentially one of the most important lessons I learned.

If you are interested to see the conference video, just have a look here.

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