I started my career as a Tech Writer in my thirties, and I felt I needed to pick up the pace and step up my tech writing game. And I needed to do it fast.
Coming from Academia, I did the only thing I knew was a shortcut to knowledge: studying.
I asked my manager and other experienced technical writers in my team for books about technical writing, specifically technical writing for software and API documentation.
Of all the books I read, these three had the most impact. They helped me stop being reactive and start being proactive in my documentation.
These books are shortcuts that allowed me to implement new and modern ideas about technical writing in my team and feel more comfortable leading other writers. Some other books may be better as foundation blocks for your career, but I’m sure these can take it to the next level.
Note: All links to the books are Amazon Smile links that support non-profits around the world.
Modern Technical Writing
“Modern Technical Writing: An Introduction to Software Documentation” is probably the most bang for your buck you’ll find if you are starting your technical writing career.
Written by my now colleague Andrew Etter, this book goes over the technical writing process as a whole, in a simple and concise read. It shows that technical writing doesn’t need to be complicated.
The book has two main sections: the Basics and the Specifics.
In the Basics section, Andrew lays the foundations through simple ideas. Some examples are defining the audience, building a website, and constantly publishing your documentation. I still read his definition of Basic Functional Documentation when writing my docs.
The Specifics section is my favorite. It pushed me to research Static Site Generators and implement them in my project. All the underlying ideas in the subsections are great: using metrics, version control, and markup languages should be a standard if you want to become a tech writer in today’s tech industry.
Definitely worth your time. Modern Technical Writing is just like good documentation: short and sweet.
Docs Like Code
Docs-like-code means treating documentation like you treat code. That is, using tools, processes, and approaches that are as unified and close as possible to the code.
Using docs-like-code and Agile methodologies to my advantage brought a lot of value to my projects through documentation. In addition, this approach helped me improve collaboration with other writers and software engineers.
Anne Gentle’s book is an interesting reference for this idea. It exposes why using this approach may help you and gives you use helpful use cases.
Modern Technical Writing gave me the final push I needed to start migrating my projects that would benefit from this approach. These books gave me the talking points I used to get management excited about docs-like-code and helped me push to transform the traditional documentation approach to docs-like-code.
I’ve seen a lot of criticism of this book, mentioning it is “too technical,” “too specific,” and “not helpful enough for end-user documentation.” I beg to differ.
Docs Like Code is more reference material than a one-size-fits-all solution to docs-like-code. This is perfect for people who want to learn about docs-like-code through a somewhat specific use case, but you’ll probably still need to do your research to find the tools that better suit your project.
The Product is Docs
I admire two technical writing teams from afar: the Stripe docs team and the Splunk documentation team. Christopher Gales and the Splunk documentation team wrote this book. And trust me, it’s worth your time.
Not only does The Product is Docs gives specific tips for every step in the technical writing process. It also has a section on hiring, training, and managing writers. This section gave me an edge when I started interviewing candidates that wanted to join my team.
I didn’t care much about their section on Tools and Content Delivery. I felt it was a bit outdated, and I’m sure nowadays they are using newer tools.
But their sections about working with other teams are outstanding. They give valuable, real-world lessons about interacting with other disciplines to improve the docs.
The other section I found interesting was the one about using the Agile methodology in your favor. If your company uses (or tries to use) Agile, you should pay particular attention.
And the underlying message across all chapters is quite simple: the docs should be treated as part of the product, not as an afterthought. This approach (and the lessons in this book) allowed me to stand my ground when working with management and engineering.
You can also read what Chris had to say about The Product is Docs in Splunk’s blog.
Extra book
I’m adding an extra book. I haven’t finished it yet (I’ve been busy with my latest project), but it sums up some of my ideas about how modern technical writing should look like.
Docs for Developers takes a developer-focused approach to documentation, and I love it for that. I enjoy writing highly technical documentation for developers, so this is just for me.
I love that the book covers the often-overlooked concepts of planning, adding visual content, organizing, and measuring documentation quality.
I’ll write a short review once I finish it.
I hope this selection of books helps you get your technical writing to the next level. What other books have helped you improve your tech writing?
In addition to this post, I started another small project called 🔗 Technical Writing links, a simple page with useful resources for technical writers in the software industry. This page includes these books and other resources. I hope you like it!