#TCCS8: Behind the scenes; what it took to write Docs for Developers with Jared Bhatti

#TCCS8: Behind the scenes; what it took to write Docs for Developers with Jared Bhatti

If you know me, then you'll know how much I love the Docs for Developers book. I always say that there aren't a lot of resources or books on documentation and technical writing process. And that's why I love Docs for Developers so much. It's one book on documentation that takes its time to painstakingly provide steps to get you from point A to point B, along with an accompanying use case story. As the authors rightfully described, it is "an approachable book about creating technical documentation".

For this episode of TCCS, I sat down with Jared Bhatti (virtually, of course). Jared Bhatti, who is currently a Staff Technical Writer at Waymo (Waymo was established under Alphabet as an autonomous driving technology company from the Google self-driving car project), was the lead writer for Docs for Developers. Before joining Waymo, he'd been at Google for 14 years as a technical writer in different capacities and departments. For fun, Jared plays the Ukulele and Drums.

During our chat, Jared shared a wealth of knowledge as he discussed what it took to write the Docs for Developers book, his time at Google, and how he advanced to managerial positions. I hope you enjoy this episode as much as I enjoyed talking to Jared.

Me: Please introduce yourself, and tell us how you started up to where you are right now.

Jared: My name is Jared Bhatti. I have been a tech writer for approximately 16 years. I've always been interested in writing, and in school, I studied English composition and Electrical Engineering. After I graduated, I worked at various startups, many of which no longer exist. At these startups, I was mostly doing engineering work, but I was also doing some writing on the side.

One day, I posted my resume on Craigslist, looking for a job. Craigslist is a wildly popular forum in the Bay Area and is a good place to find a job. A recruiter from Google reached out to me and said, 'hey, you have this really interesting assorted set of experience. I think you'd be a great technical writer here at Google'. So I interviewed for the role and passed.

Before that, I had never worked a formal technical writing job, yet I found myself documenting Ads. I worked on that for a few years before switching to something closer to electrical engineering: documenting Google's hardware platform (our power distribution systems, the servers, networking fibers, and things like that). After a few years, I moved again to Google Cloud, where I helped start the Google Cloud technical writing team. I was the first manager there and grew the team considerably for seven years before moving to Waymo, where I currently document autonomous vehicles. So it's been a really exciting career journey. And along the way, I wrote Docs for Developers.

Me: You have no prior technical writing experience prior to Google. So, what did you do to improve your technical writing skills and succeed at work?

Jared: Oftentimes, when tech writers (who do not have engineering backgrounds) sit down to talk to engineers, their major challenge is a knowledge and terminology gap, which inhibits understanding.

That was my advantage: I was very comfortable with engineering and communication. My ability to sit down with engineers and easily comprehend all the information they dumped on me was my superpower. Even though I lacked formal expertise in organising information, I used that advantage to build trust, which was key to getting information from engineers.

I learned all of the other pieces along the way. And I was lucky to have some great mentors at Google who saw my potential and helped me improve as a tech writer. So now, when I mentor someone, I try to find out if they have more experience in writing or engineering and help them fill in the gaps.

Me: So what should someone with more writing experience do to close the technical gap?

Jared: I would recommend learning some fundamental programming language (Python or Ruby, or Javascript), and just learning enough to build a small app to get a basic understanding of how things are built.

While doing that, you may also get the opportunity to learn some of the modalities of technical writing based on some interesting resources you might find. Mm. For example, when I started learning Ruby, I discovered there's a really good free online graphic novel called 'The Poignant Guide to Ruby'. It's a fun way to learn Ruby through a cartoon mouse and a bunch of really cheesy jokes about bacon. That experience helped me see and learn a different format of tech writing.

I'd also suggest getting a mentor, and Write the Docs is an excellent place to find mentorship. I met all the people I wrote my book with through that community.

Me: After working within Google for over 14 years, what prompted your move to Waymo?

Jared: The short story was that I felt I was due for a new challenge. After working on the cloud, where the hardware is not visible, I was yearning to do something more hardware-based again.

I wasn't planning to switch, but the opportunity came up, and I just went with it. Waymo had been looking for their first technical writer for about a year and a half, and they were looking for someone with very specific skills. One day, I got talking with the hiring manager, and as we talked, I realized that I might be the person they were looking for. I figured I could have a lot of impact here.

Me: So, do you get a personal Waymo as part of your compensation? I mean, since you have to test it?

Jared: Hehehe. I get the joy of riding Waymo vehicles for free in San Francisco.

Me: I imagine you didn't know much about Waymo's technology when you joined. So, what did you do to get the necessary knowledge to contribute value as quickly as possible?

Jared: Waymo actually does a pretty good job with onboarding engineers. When I joined, I went through the engineering onboarding, which is something tech writers should do. If your company has a non-technical onboarding and they try to push you to do that, don't do it. Do the engineering onboarding, since you'll be working with engineers. You need to know everything that they're doing.

One thing I did to contribute value, even while still in onboarding, was to find the gaps in onboarding. As a tech writer, you will discover communication gaps in your initial few days; trust your instincts on this. I noticed that different departments had their own glossaries and siloed docs. I took on consolidating all the individual glossaries, and when I did, everyone was like, 'wow! I don't know how we operated without this'. Now everyone can look up all company-wide terms from just one location.

Me: You've been a technical writing manager. What steps must a senior technical writer take to qualify for a management position?

Jared: The first step is to understand that managing is very different from working as an individual contributor. You will be responsible for all the people reporting to you and doing a lot less technical writing. Instead, you'll be focused a lot more on coaching, mentoring, navigating organizational issues, having hard conversations, setting standards, and advocating for technical writing. And when you first start, you probably won't be very good at it.

I already mentioned Write the Docs. There's a whole group of tech writing managers in that Slack channel, and they're always asking each other questions about managing and giving each other feedback. That's a great place to learn and get help.

Me: Let's talk Docs for Developers. When did you get the inspiration, and what inspired you?

Jared: I got the inspiration to write a book because I found myself answering a lot of similar questions for people at Google and particularly in Kubernetes. Zachary Sarah and I were working with writers to onboard them into this open-source project, and we found ourselves giving the same advice over and over again. And so, Zachary suggested that we write a book on open-source docs.

As we started researching, we realized that the number of people who would buy a book about technical writing in general, was much higher than the number of people who would buy a book on open-source docs. And there also wasn't any good book on just technical documentation in general.

We also realized that we needed expertise outside of our own. So we started reaching out to folks that worked at startups like Heidi Waterhouse and Jen Lambourne. David was from Stripe, and their docs are amazing.

It also turned out that each one of us had a book in mind. So we took all those book proposals and kind of Frankensteined them into one book and cleaned it up a bit. And that was the proposal we went with.

Me: What challenges did you experience while pitching?

Jared: We experienced some challenges and pushbacks while pitching to publishers, one being the general notion that books with a lot of co-authors don't usually get written due to creative differences or infighting. This was strange to me because I thought it would be more compelling. After all, more writers meant more expertise, but it was actually less compelling to publishers.

To tackle that, we added another section to our pitch on how we planned on working together. The section detailed our process our decision-making process and how we planned to commit to completing the book on schedule.

Another challenge was that publishers wanted the book to be a 'Google process' book. For example, when we pitched to publishers like O'Reilly, they asked, "is this gonna be the Google process for technical writing?" We said, "No, it's just going to be a general guide to writing technical documents." And they said, "well, if this was a company book, we might be a little more interested." That was kind of a surprise for me. But, I think it's because they had published a number of books on different 'Google processes' that sold really well.

Me: How did you combine writing this book and keeping your full-time job. Care to share your scheduling secrets?

Jared: We were pretty bad with our initial schedule. We thought we would bang out this book in three or four months because we were all writers. In retrospect, It was an absurdly short timeline. Everyone I know who had written a technical book told me to give myself a year. And I was like, 'Oh no, we got this'. Well, we didn't.

What I ended up doing was scheduling, usually two days a week, and just sitting and writing for a couple of hours. Each of us was working on one or two chapters in the book and also agreed to peer review each other's chapters.

Then Sarah agreed to be the editor-in-chief to ensure all of the chapters had the same voice and tone because we all had distinct writing styles. That was our approach. And it worked pretty well and took us a year to write it.

Me: What were some challenges you all encountered while writing the book?

One of the hardest things we had to do was figure out what was in scope and what wasn't. Different companies or teams will have specific docs or additional docs they'll need; How do we create a real-world example that everyone would relate to

David actually gets a lot of credit for drinking half a bottle of wine one night and cranking out a little story that we could sort of wrap the book around: the story of From there, things kind of fell into place.

We also had a huge debate about information architecture because while it is really key to organizing information, it's an advanced topic. Our target audience was engineers who needed to create good documentation, maybe because they didn't have a technical writer on their team. So everything that was not going to be useful or too much needed to be cut off. In the end, we compromised on that one because it was so important that we kept a chapter, but we tried to keep it fairly light and point to other materials. We also made a lot of effort not to favor any tool because doc tools change, and they go out of date quickly.

That's it. There were no real personality conflicts. We actually had a lot of really good conversations, and I learned a ton from everyone I worked with.

The End……

Some last words…

  • Docs for Developers is being translated into Japanese and will be out in February or March of next year. So if you want the book in Japanese, keep an eye out for that.
  • If anybody wants advice on how to write a technical book or pitch to publishers, Jared is willing to share his detailed process with you. Reach out on Twitter or LinkedIn.

More articles you might like:

Get your technical writing career off the ground.

Join over 1000+ subscribers just like you. Every month, I'll send you new articles and expert interviews published on the blog, so you'd never miss out. I'll also send you a curated list of other valuable resources on technical writing across the internet, as well as fully-remote technical writing gigs/jobs to help you land your dream job.