I didn’t write The Great American Novel during the pandemic. I’m good with that. Instead, I worked with an amazing team to write the best book we could on how to do technical writing when you are not a technical writer.
I finally believe this book is really real, because look, there are pre-order buttons!
About Docs for Devs
We wrote this book because we needed it to exist. We looked all over the market and didn’t find anything for “crap, I am a code-type person, and now I have to write documentation”. We know that scenario happens all the time, because we see it in our companies, or we get hired on after it’s happened, or we are using documentation that developers wrote reluctantly.
Every time we talked about documentation around code people, they would ask us if there was a book or website where they could learn just enough documentation to get by. This book is not written for technical writers. It was written for people who never expected to be technical writers, but still have to make technical documentation happen.
We included the basics — how to get started, how to figure out what needs to be written, and for whom, where the code samples and images go, how to make a pile of documents make organizational sense. We know that there are devs who need that. We have also included some indicators for when it’s more than a developer should have to do, when it’s time to hire a professional technical writer.
Lots of people think that technical writers are only for external documentation, or only for big teams, but they can be a force multiplier for lots of teams, including the ones working on internal tools or processes. I used to have a sticker that said “Better and cheaper than making your devs do it”, and I still believe that’s true. I just also believe that there are lots of times you can’t win that argument with the powers that be. This book is for those times.
We left out so so many things that we care about, that we think are important, mostly because they were important to us as writers, and wouldn’t necessarily help a developer. We were intentionally vague about tools and software. We didn’t get into localization or accessibility standards much. We had a long talk about taxonomy, but cut it down to the barest bones. We have a huge parking lot of topics that we decided were too advanced, or too niche to be in this book. If you find one of those gaps the hard way, I’m sorry. We did it on purpose.
We hope that this is the book that you needed. The one you give to your team so they write better error messages and API docs, the one you keep on your bookshelf to refer to when you are stuck on making yourself understood. The book that you read when you’re in a code bootcamp to be just that much more ready.
Writing is hard, we know. It’s just better than not having written.
The rest of this post is pretty long, but may be interesting if you’re looking to write a technical book.
How we did it
The team was Zachary Sarah Corliessen, Jen Lambourne, Jared Bhatti, Dave Nuñez, and me. I think at one point we added it up and our combined technical writing experience was getting close to retirement age. It was kind of intimidating, really! But it was also exciting, because we could have the kinds of discussions you only get with deep, shared expertise. We talked about the techniques that we had found worked, or didn’t work, in different environments. We tested each other’s procedures and worked through our assumptions. We met almost every week for over a year.
We started by wrangling about who our target audience was. Were they at a big company or a small one? Were they doing open source? Were they doing internal or external documentation? This is where we started to see the benefits of having a diverse team — we had all worked on different kinds of projects and could speak from experience about who gets assigned to write docs, and what kind of resources they have.
Meanwhile, we were also tapping our network for other people had published to get a line on how to write a book proposal. We couldn’t have done it without help from Brian MacDonald, VM Brasseur, Anne Gentle, Torrey Podmajersky, Erin McKean, Sid Orlando, and others.
Writing the proposal forced us to put together a rough outline and start thinking about marketing and what kind of book we wanted to be writing — how long would it be, who would it be for, that kind of thing.
We put together a chapter and heading outline and shopped the book around. We had some pretty clear ideas of what we could and couldn’t write, and what we wanted, so not every publisher was right for us.
We split up the chapters and started writing. This wasn’t easy, but it was at least the part of the process we were most familiar with. After a chapter was written, we all read it and made comments, and Zach did a first-pass copyedit.
The things that we found more difficult or unfamiliar were things like sourcing graphics, dealing with layout software we weren’t in charge of, publishing schedules, and line edits that we had to trust to other people. Basically, all of the parts with publishing were us learning to breathe past our internal control-freaks, because that’s usually our job to manage. Agreeing on the title was most of 3 meetings, as I remember.
Once the chapters were drafted, we worked to stitch them together, to create a central narrative line through all the things we were talking about to make it easier to follow. We debated a few chapters up to the very end — was this a basic topic or and advanced topic? Did we get too deep into the weeds? Were we missing something obvious to us?
Literally between submitting and finalizing, we found out that someone had started a company using our example-company-name, so we had to change that through the whole book!
Now that we’ve handed off to the publisher and approved the final, final, no really-the-last edit, we have to do marketing and promotions, which, uh, is not something we have a lot of practice with. We put up a website (docsfordevelopers.com), and Jen waded through all the red tape to get a .ly domain extension for corg.ly.
Each of us wrote a few chapters, but we also all brought our experience to the book as a whole. I am a terrible copyeditor, and project management and taking notes in meetings are not my strong points either. I can’t really draw diagrams, I don’t know how to negotiate with an illustrator, and information architecture is not my nerd. I could not have written a book this good alone. Better together is really a key part of this project.
What we learned
It really takes excellent planning and project management to get through a project this big.
Asynchronous work for deep work and thoughtful writing, synchronous meetings for group consensus and ideation.
You’re not going to get rich writing a technical book, but at least you can tell people to buy it to solve known problems.
The publishing process is longer and more stressful than you think it will be. Even if you think it will be long and stressful.
A team of kind, committed experts can get through a project like this, even with major philosophical differences, and like each other even better on the other side — if they work on staying kind. YOU ARE THE BEST, TEAM!
Top comments (1)
Getting it for my team!