SPLUNK LIFE

The Product is Docs

The Splunk documentation team wrote a book!

Yes, of course, we write books all the time to help all of you become productive and confident when you use Splunk software. In talking with our industry colleagues, however, we also discovered that there is a lot of interest in how the Splunk doc team does its work.

We are very pleased to announce the publication of The Product is Docs: Writing Technical Documentation in a Product Development Group, now available on Amazon.

What does this book cover?

Although there are already books, articles and conference presentations about many aspects of working as information developers and managers of documentation teams, in developing our own internal practices, we found numerous gaps.

For example, when we went to create some audience definitions, to our surprise we found that there were no good models to follow specifically for technical documentation. There is a lot of material about persona development for user experience teams, and audience definition for marketing purposes, but nothing for technical documentation even though every doc team in the world discusses audience all the time.

Similarly, there's a lot of good material about working with subject matter experts in engineering or teaming with UX, but a lot less about working with QA, customer support or product management, which are all groups that play a significant role in our daily work.

The more we thought about it, the more the list of underrepresented topics grew. And even for topics that had significant published resources (doing documentation in an Agile environment, collaborative authoring, working with remote teams, and others), we couldn't find anything that felt current and accurately reflected our daily working practices. We wanted a book that covered the reality of developing technical documentation in a fast-moving product development organization, and we discovered that the book we wanted didn't exist.

From a hack week project to a final product

We kicked off the writing effort as a hack week project, with most of the Splunk doc team contributing messy rough drafts in an effort to capture as much of our thinking as we could in the shortest possible amount of time.

In five days, we wrote 90 pages that formed the basis for the entire book. From that initial 90 pages, we worked in teams of two and three to expand the content and fill out those preliminary thoughts until the rough draft more closely resembled the book we are announcing today. Then we took a couple of individual passes through the entire manuscript, followed by a final round of team read-throughs and several months of further revisions.

The project took over a year, but the final product remains true to its hack week origins and stands as a testament to the creativity, spirit and expertise of the Splunk doc team.

Who is this book for?

This book is for you! It's unlikely you would have read this far if you weren't interested in it. Perhaps you are a technical writer in a small, high-growth company that is still figuring out its processes. Perhaps you are an information-development manager in a large enterprise company with an expanding product line and an ever more complex matrix of cross-functional dependencies. You might work at a medium-sized company where your management is asking you to do more with fewer people and you want some additional perspective that will help you find a leaner and more effective way to deliver what your business demands. Or you might work outside the technical documentation world, in another part of product development, and be wondering how to collaborate most effectively with the documentation team.

If you work as an information developer, a manager in a documentation team or in another product development role that collaborates with the doc team, there's information in this book for you.

We think you and your colleagues will find it worthwhile.

All proceeds from the sale of The Product is Docs will go to charity.

Christopher Gales
Posted by

Christopher Gales

I have over 20 years of experience growing and managing globally distributed information-development teams that produce content for end-user, enterprise, and developer audiences. I have been a member of the Center for Information-Development Management Advisory Council since 2013, and I have presented to global audiences about strategic planning, metrics, and community engagement. I live in the San Francisco Bay Area, have a family, and pride myself on knowing who to ask.

Join the Discussion