Documentation is Teaching, and Teaching is Everything

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

Documentation is notorious for being in a persistent Schrödinger state. Everyone wants good documentation, but nobody reads it. Writing good documentation is “easy”, but nobody wants to write it.

Documentation is absolutely necessary, and carries equal rank with code, because if nobody knows how to use your software then they won’t use it. You say you want contributors? They need to know your needs, policies, tools, workflow… you can’t depend on finding miraculous magic contributors, and must communicate your requirements.

Documentation takes many forms. It is formal manuals, like our very excellent SUSE manuals. (You know the other enterprise Linux? Our manuals are way better.) Documentation is videos and screen casts, tips and tricks, Wikis, helping users in forums and on mailing lists.

Documentation is blogs like this one. You can write blogs to publish here, yes, you! Which brings us back to our paradox: a lot of people dismiss writing as easy, but somehow never quite get around to performing this “easy” task themselves. The reality is writing documentation is both easy and difficult. It is easy to write a brief blog sharing something that you think is cool and useful. It doesn’t have to be long; a few paragraphs about a new feature, some cool obscure command options, an important update… the idea is to share your enthusiasms. Small is beautiful, small is useful, and customers love having this connection to insiders.

Writing is hard when it’s formal, structured, and long like the splendid SUSE manuals. For example, the SUSE OpenStack Cloud 7 Deployment Guide is just one of a set of five Cloud 7 manuals, and it is 360 pages long. Simply organizing the information across five separate manuals is a heroic task. Do I need to remind you how complex SUSE OpenStack Cloud is? How it is a moving target under continual change and development? How a small error or omission has the potential to cause great unhappiness to customers? Customers need to know how to use our products, and this is not optional. They need answers. We are the answer people, and must deliver a positive experience.

Good documentation serves a multitude of users: paying customers, potential customers trying our free downloads, SUSE employees in all departments, journalists, howto authors, consultants… everyone wants answers, and the easier we make it to find answers the stronger we’ll be as a company and a community.

Teaching is the most noble profession, because nothing is more important than knowledge. Documentation is teaching, and teaching is everything.