Christopher Gales - The Product is Docs: Writing technical documentation in a product development group

The Product is Docs

Writing technical documentation in a product development group

Christopher Gales and the Splunk Documentation Team

Copyright 2020 Christopher Gales

All rights reserved.
Splunk is a registered trademark of Splunk Inc. in the United States and other countries. All other brand names, product names, or trademarks belong to their respective owners. Any use of a trademarked name without a trademark symbol is for readability purposes only.

Contents

In the two years since we first published The Product is Docs , the book has found an enthusiastic audience of documentarians, designers, product managers, developers, customer success managers, sales engineers, teachers of technical writing, and more. The royalties from the book have enabled us to donate thousands of dollars to a dozen different charities. And most important, the book has had the effect we hoped it would: to spark productive discussions in teams and companies around the worldand in the technical writing profession itselfabout how to write technical documentation in a product development group. As just one example, two months before the publication of this second edition, a collection of Write the Docs community members gathered in a Slack channel to read a chapter every day and discuss it. We avidly followed that conversation and took a lot of notes, many of which are incorporated into this volume.

The other changes and additions are the result of the past two years of experience within our team and our products group, and also because we thought of a few things we just plain missed the first time.

Here are the new chapters:

In addition, we made substantial revisions to the following chapters:

We also made smaller revisions throughout the book to bring it up to date with the trends and changes we have experienced in product development, technology, and within the technical writing profession itself, as well as to address the experience of technical writers who work in small teams or who are the only writers at their companies.

Finally, we gave the whole thing a good, solid edit to tighten and polish the entire manuscript.

If youre picking up this book because you read the first edition and found it useful, welcome back! We greatly appreciate you as a returning visitor, and we hope you find this new version even more useful for yourself and your colleagues.

If youre finding The Product is Docs for the first time, read on! The introduction explains why the book exists and who its for. Please read, discuss, share, and apply whatever parts of the book help you. We dont pretend to know all the answers, but we do believe that describing what we do and how we think in our team can help other teams across the industry and around the world evolve their own practices, do better work, and help their customers be more successful.

In the course of doing our work, the Splunk documentation team strives to adoptand adaptindustry best practices whenever we can find them. And when we cant find them, we make every effort to develop them.

There is a substantial body of professional literature on the content itself, including content strategy, user and task analysis, and the right way to design and structure technical information. On the project management side, JoAnn Hackoss pioneering book Managing your Documentation Projects is still a keystone work, but it was written and published before the Agile Manifesto ( http://agilemanifesto.org ) transformed the world of software development. Her subsequent Information Development: Managing Your Documentation Projects, Portfolio, and People provides an update for Agile, but it focuses exclusively on the technical communications manager and is out of print.

There are articles and conference presentations galore about many aspects of our work as information developers and managers of documentation teams, but in developing our own internal practices, we have found numerous gaps. When we went to create audience definitions, to our surprise we found that there were no good models to follow specifically for technical documentation. A lot of material exists in the wild about persona development for user experience (UX) teams and audience definition for marketing purposes, but nothing exists for technical documentation, even though every doc team in the world discusses audience all the time.

Similarly, we have found good material about working with subject matter experts (SMEs) in engineering or teaming with UX, but we havent found much about working with quality assurance (QA), customer support, or product management teams, which are all groups that play a significant role in our daily work.

The more we thought about it, the longer the list of underrepresented topics grew. And even for topics that had significant published resourcessuch as creating documentation in an Agile environment, collaborative authoring, and working with remote teamswe couldnt find anything that felt current and that 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 didnt exist.

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. From that initial 90 pages, we worked in twos and threes to expand the content and fill out those preliminary thoughts until the rough draft more closely resembled the book youre holding today. Then we took a couple of individual passes through the entire manuscript, followed by a final round of team read-throughs and minor revisions. It took us over a year to write it, with collaboration as our guiding principle throughout the process.

Who is this book for?

This book is for you! It is unlikely you would have picked it up and read this far if you werent interested in it. Perhaps youre a technical writer in a small, high-growth company that is figuring out its processes. Perhaps youre an information development manager in a large enterprise company with an expanding product line and an increasingly 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 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 are wondering how to collaborate most effectively with the documentation team.