Finding your voice when writing a technical book

By Greg Turnquist

Greg L. Turnquist worked on the Spring team for over thirteen years and is a senior staff technical content engineer at Cockroach Labs. He was the lead for Spring Data JPA and Spring Web Services. He wrote Packt's best-selling title, Learning Spring Boot 2.0 2nd Edition, and its 3rd Edition follow-up along many others.

July 7, 2014

learning-spring-boot-ch3Something that I have been polishing for some time is my writing voice. The voice is more than just words, grammar, and speaking in a me-to-you, versus us-with-us style. It’s the way we blend words and language together to provide our writing with a certain personality. One of the things that won me over before I got past page one of Killing Floor, the first Jack Reacher novel, was the voice.

In that page, the dialog was 1st person, coming from Reacher himself. It was calm, clear, and crazy. The man was being arrested. Why? Unknown. And yet, Reacher didn’t tremble a bit. He had no fear. Again, why? I would panic! On top of that, Reacher calmly moves such that no one ELSE in the diner is put at risk. What?!? I had a clue who he was, because I had seen the movie. But subtracting that, you DON’T know who he is, and this type of uncharacteristic reaction to three cops with loaded firearms made me hunger to turn the page. Again and again and again. The voice grabbed me and held onto me through the whole book. And to the next book. (I’m not on #10).

Since I started writing this blog six years ago, my writing style has matured. I have slowly found the way I want people to share the thoughts I am putting down. I want it to be fun and not a cold lecture. I want to invite people in, and hunger to read my next post. And my next one after that.

When I wrote my first book, Spring Python 1.1, I was new to the idea of writing a book. I struggled with being concise. Boiling ideas and concepts into simple, well crafted sentences. I wanted the reader to enjoy what they were seeing and be able to think of ways they could use the code to meet their own needs. I didn’t think much about my voice, but instead more about the content.

When I embarked upon writing Python Testing Cookbook, I was much more confident. I had a big vision of what I wanted to tackle, how I wanted to tackle it, and what was important to me. I also had a better sense of time management and what it took to get things done. And I had a clearer picture of Packt’s shortfalls that I needed to watch to make sure the release was top

So as I began writing Learning Spring Boot, I had much more creative energy. I had even launched a separate financial blog two years ago and reached a rhythm of blogging two posts/week. To top it off, last summer, two other devs and I had been tapped to write over fifty getting started guides. I spent all summer writing technical stuff. We worked hard to find a common voice the three of us could share with the intention we would spread it to others to decentralize the writing in the long run.

All that writing I felt had improved my writing on several fronts. I had more self confidence to write in the voice that I chose. I had also honed my blogging voice. I was interested in the long run of people being able to read my book, and then visit my blog, and find some familiar writings. Or the other way around. And I had learned how to write for different audiences with different voices.

Here’s a sample from chapter nine of Python Testing Cookbook:

Testing isn’t a cold, mechanical process. It’s an exciting, fiery area of development. Test bitten developers can’t wait to share it with others. If you look for ways to spread the fire of automated testing, eventually others will warm up to it and you will find yourself talking about new testing techniques together. –Greg L. Turnquist, Python Testing Cookbook, p.330

If you read Scheduling Tasks amongst Spring’s Getting Started guides, you won’t find this same voice. You’re not supposed to. You’re supposed to find an entire collection of guides with a somewhat uniform style that show you how to solve common problems quickly. Making these guides consistent, uniform, and simple took an arduous amount of effort.

But if you switch to reading this blog, you’ll find a different style entirely. It’s more personal, because this is my personal blog site. I want to write enticing articles that you’ll enjoy.

And in Learning Spring Boot, here’s a sneak peek of some of my prose from Chapter Two: Quick Start with Java:

For production-ready support, it’s nice that Actuator provides us handy data we can consume. The scripts we used to consume these metrics might seem a bit crude. But in the real world, we need tools that let us quickly try something out before investing in bigger, more complex, and often more expensive solutions.

If our manager wanted a quick read on the last twenty four hours of data, we could easily take `metrics.groovy` and adjust it to have a rolling time limit. We could then serve up the content using a little Spring MVC. Cash in on Spring MVC’s WebSocket support, and we could have the screens update dynamically. Program managers love eye candy, right?

There’s no telling what requirements we’ll get from sysadmins and managers. Spring Boot’s easy-to-consume endpoints provide us the tools we need in both our main application and the support tools we’ll build up to manage things. –Greg L. Turnquist, Learning Spring Boot

I am receiving feedback from a couple of my colleagues as well as an editor. I have to sift through this material and decide what is an undeniable improvement (faulty words, typos, bad grammar) vs. stylistic changes. And when it comes to stylistic changes, I have to figure out which things will improve my story and which things impede my voice. I want to polish my voice and nothing helps better than honest, objective feedback from others.

So if I’ve held your attention this far,  I hope that perhaps you are also thinking of writing. I wish you the best of luck, and never to be afraid of asserting yourself to define your own voice.


Submit a Comment

Your email address will not be published. Required fields are marked *