I'm very pleased to announce the publication of the revised and expanded second edition of The Product is Docs: Writing technical documentation in a product development group, available now on Amazon. Once again, the Splunk Docs team has pooled its effort and expertise to share our practices with the broader community.
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 world, and in the technical writing profession itself, about 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.
We have added the following new chapters:
- Documentation Decisions
- Organizing Documentation Tiger Teams
- Working with the Field
- Writing SaaS Documentation
In addition, we we made substantial revisions to the following chapters:
- In "Customer Feedback," we added a new section about working with the community and retitled the chapter accordingly.
- We reorganized and streamlined "Documenting Third-Party Products," improving the decision tree and aligning the chapter content to provide clearer information about each of the scenarios.
- We updated "Hiring, Training, and Managing Documentation Teams" to include some discussion about diversity and inclusion, and the benefits of establishing diverse teams.
- The "Technical Editing" chapter underwent a complete rewrite, to describe the different aspects of technical editing more clearly, to emphasize the ways in which writers and editors collaborate, and to provide guidance and techniques for writers working in companies that don't have technical editors.
We also made smaller revisions throughout to bring the book 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 are the only writers at their companies. Finally, we gave the whole thing one more good, solid edit to tighten and polish the entire manuscript.
If you are reading this blog post 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 you are finding The Product is Docs for the first time, see our initial blog post to read about why the book exists and who it’s for. Take a look at the new edition. Please read, discuss, share, and apply whatever parts of the book help you. We don’t 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.
And, as always: we welcome your reviews and feedback!