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

by Christopher Gales, Splunk Documentation Team

Revised and expanded in 2020! This book provides a broad perspective about the essential aspects of creating technical documentation in today's product development world. It is a book of opinions and guidance, collected as short essays. You can read selectively about subjects that interest you, or you can read the entire collection in any order you like. Information development is a multidimensional discipline, and it is easy to theorize. We have written this book from our direct experience, using the concrete insights and practices we apply to our work every day. If you work as an information developer, a manager in a documentation team, or in another part of product development that collaborates with a doc team, there is information in this book for you. Perhaps you are a technical writer in a small, high-growth company that is 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 are wondering how to collaborate most effectively with the documentation team. The purpose of The Product is Docs is to provoke discussion, shine light on some murky areas, and—we hope—inspire our colleagues to consider their processes and assumptions with new eyes. All proceeds from the sale of The Product is Docs will go to charity.

Genres: Nonfiction, Writing, Technology, Reference

293 pages, Kindle Edition

First published January 1, 2017

Reviews

[M · Rating 4 out of 5]

Managing documentation can be a lot like herding cats in a dumpster fire where many cats have managed to set fire to their own tails and they attack you when you try to help them.

I feel like this book touched on the fact that there are cats and you'll need to herd them. If your company doesn't have a budget for documentation or a deep understanding of its value, then you're probably in the dumpster fire. There's a lot of great information in this book and I enjoyed learning about how a larger documentation team operates.

There was one thing that I found a bit tiresome about the book, and that was the whole "engineers are busy and their time is valuable, product managers are busy, and customer support is busy..." and all of that is true, but you know who else is busy and whose time is valuable? The documentation team. I've held roles in engineering, support, QA, and R&D in addition to documentation. There's just no need to emphasize these other roles that way and enforce an unnecessary hierarchy.

[Carlos Ramos · Rating 2 out of 5]

This book had not much to do with writing, and much more to do with the "how to work with people when you happen to be a writer".

I read it from cover to cover and, being an unofficial writer for internal documentation at my workplace, I did not relate to much of the content, and found it boring, with a preacing tone.

If you work with several people, yeah, it may provide some valuable information. But, in case you are a solo writer, nah, not much information there to justify the reading.

[Paulo Ribeiro · Rating 5 out of 5]

I must congratulate the Splunk documentation team for the amazing book on Technical Writing that they have put together.

It's the book on Technical Writing that I've read so far that is most packed with useful information and that covers the widest range of aspects in this field. The sheer density of information per page that this great little book manages to pack is what makes it so valuable.

I've been a Technical Writer for almost 15 years, and 99% of what I read in this book resonated deeply with my own experience. The book works well for someone like me who already has some experience in the Technical Writing field since the summarized / dense writing in the book acts like reminders for our past experiences and only the interesting bits need to actually be in the book.

Another thing that this book makes a case for is taking ownership of the documentation for a product as a product in itself. This makes immense sense and it's only with this mindset that Technical Writers can bring the most value to users, the product development teams, and the companies they work for.

I highly recommend this book to anyone who practices Technical Writing, manages a team of Technical Writers, or has a closer connection to a documentation team.

[Michael McLoughlin · Rating 5 out of 5]

A real world look at technical writing for software

I think this is one of the best tech writing books I've ever read and contains the kind of information about the real job of information development in a modern software house I wish I'd had when starting out in the industry.
It's not a writing manual, or a manifesto for tech authors. It explains the role and purpose of technical writing within software development and how writers can interact optimally with other departments such as QA, Support, UX, Dev etc.
Well worth the read for experienced writers too. And all the proceeds go to charity. What's not to like?

[Christopher Williams · Rating 5 out of 5]

Valuable real-world details on technical documentation! From the team at Splunk, this book gives us not just a window into the ins-and-outs of technical writing. It gives helpful advice along each step (organized in short, punctual chapters) to navigate and do well. The focus is on producing good documentation within a team, whether it's a team of software developers or corporate management.

Some chapters have greater detail than others. (Hey, nobody's perfect.) If that's the only caveat though, you've got a winner on your hands. I would gladly recommend this book to people interested in tech writing, novice writers, and even writers in other fields looking to switch to documentation.

[Magdalena WR · Rating 4 out of 5]

Splendid read. Finally something full of valuable information about working with docs.
Each chapter is designed as an independent part so that I could begin whenever I wanted - it was a bit tiring to read it all from cover to cover.

[Simon MacDonald · Rating 4 out of 5]

I admit that i'm not the target audience for this book. Initially, I thought it would be a book about how to write high quality documentation. Instead this is a manual for how tech writers can survive and thrive in big corporations. It's excellent advice but not exactly what I was looking for. The book was recommended to me, so I bought it sight unseen.

One quibble I have is the printing of the book was bad. Many of the pages were offset or printed on an angle. Also, there wasn't enough spacing between the end of the prose and the page number so I often found myself reading the page number as part of the sentence.

[Rebeck · Rating 5 out of 5]

Just settling into the field after four years of on-the-job learning, and found this more relevant than any other book I've read on (or around) the subject. Teammates and I regularly discuss/debate best practices on each of the topics covered, and I'm pleased to see many of our own conclusions validated here. I especially liked the chapters on communicating/collaborating with other disciplines. Put the highlighter to work.

[Elle · Rating 5 out of 5]

I am a college senior majoring in Technical Communication, and interning as a technical writer. My first project felt unsettling, but I didn't have the words to explain why.

Yesterday I picked this up, opened to the middle, and read a section. It resonated so profoundly, and after reading two sentences I started underlying sentences and writing notes in the margins.

The beauty of this book is that it's written like technical documentation. You don't have to read each page in order to understand the information. A few chapters do recommend previous chapters, but they're clearly listed. I flipped around a bit at first, and read the chapters that applied to my situation, and then went back and read from the beginning to reread my applicable chapters in context.

This book addressed my technical writing insecurities. Now I'm confident and prepared to take my writing from engineer copyediting to being an integral member of the project team!

[Renée · Rating 5 out of 5]

As a lone technical writer, this book gave me a lot of useful advice for improving content development processes at my company. Hats off to the entire Splunk team for taking time to put this together.

[Keith Brooks · Rating 4 out of 5]

If you need to know, this is the way to go.
1 star loss for the weird formstting of the book.
For a book about writing, they need a better style :-) the skewed paragraogs abd odd chapter starts on different pages seemed out of place.

[Shandi · Rating 4 out of 5]

We read this book for work and it was SO helpful for me as a content/technical writer.

[Jordana Simon · Rating 4 out of 5]

Very good book about how to make a great documentation for a great product. It's very long with some things that don't really matter. But the essence of it is important. To reread every now and then

[Mel · Rating 5 out of 5]

Great book with lots of practical advice and reasons for why the authors suggested certain things. I’m definitely going to come back to this one.

[sam · Rating 1 out of 5]

DNF. Boring, repetitive, and offers little insight into anything useful.