If You Think Producing Good Product Documentation is Expensive, try Calculating the Cost of Not Having It

When last we met (How to Keep Customers Happy and Liking Us a Lot, part 1), I discussed the importance of product documentation, and how merely flinging code out the door is not adequate for a fabulous enterprise open source company. Today I talk a bit about the cost of not having good product documentation.

The lunch bunch discusses SUSE Linux

Product documentation is a bit of a paradox. We writers are stuck between “Nobody reads documentation”, “We don’t need documentation”, “Anyone can write, it’s no big deal”, and “Hey, where is the documentation that I need?” Of course we need to provide documentation, and if writing is easy and anyone can do it, then why don’t they? Customers, support engineers, developers, marketing and sales…everyone who ever touches our products depends on documentation.

Imagine a user, a potential new customer, downloading SUSE Linux Enterprise Server to try, and then they can’t figure out what to do with it. How much effort do you think they will exert to become a customer? Trick question, as it is not their job to fight their way to becoming a customer. It is our job to provide the information they need to use our products in a satisfying and productive way.

Documentation takes multiple forms and isn’t limited to text manuals. It can be formal teaching videos, informal tips and tricks videos, blogs, knowledge base articles, slides, podcasts, heck, put it into rhyming couplets and songs with interpretive dance, whatever it takes to provide a great customer experience.

Time is Money

We doc writers represent the customer. We are the only ones in the development process who use the products the same way that our customers do, installing, configuring, administering, upgrading, uninstalling, integrating with random software and hardware, trying to do weird things that no one person or team can completely anticipate. We don’t rely on automated tests, but make our testing as real-world as possible.

In my ideal world we don’t have to bang around and try to figure out everything ourselves. It is far more efficient to first learn from whoever wrote a particular feature, or whoever has expert knowledge of it. My favorite process is getting a basic howto or quick demo from said expert, then I try it out, come back with questions, write it up, and then the expert gives it a technical review. That bit of extra time that the expert invests in teaching me results in giant time savings for everyone else. How much time does it save? Let’s say our expert spends a total of two hours helping me. Think about the last time you spent frustrating hours trying to figure something out, searching the product manuals, knowledge base articles, web searches, Stack Overflow, online discussions, and roaming the halls of SUSE trying to find someone who knows anything. Think about customer frustration, and how much support tickets cost. In comparison, that two hours of expert time is dirt cheap.

I appreciate the cooperation and help I get every day. SUSE is full of excellent smart helpful people, and you are a joy to work with. Still, the process could use some improvement. We support every product release that is not end-of-life. For SUSE Linux Enterprise Server alone that is six releases. We are continually improving our efficiency, but it is still a lot of work, and we have to rely on other teams every day to get our work done.

In my ideal world we have enough staffing and resources to keep up with new features and release updated documentation with every product release, handle bugfixes quickly, and brainstorm new cool methods of information delivery; product documentation is a formal part of the development process, and engineering has time budgeted to work with us.

Becoming the Standard

There are sayings, “eat your own dogfood” and “drink your own wine”. These means that as a company, everyone in every department should use our own products as much as possible. It looks bad when we don’t, like we don’t have faith or pride in our own products. It’s also a great way to do real-life testing and improvements without endangering customer relationships– isn’t it better to find and fix problems before customers do?

One of the biggest hurdles to migrating away from closed proprietary products is data and document incompatibility. Free/open source software have been chasing proprietary companies from the beginning. I think it would be marvelous to go on the offense, and attack the perception that proprietary companies are the standard to chase, and instead become the standard that they have to pursue.