Docs for Developers: An Engineer's Field Guide to Technical Writing


A book by Jared Bhatti, Zach Corleissen, Jen Lambourne, David Nuñez, Heidi Waterhouse

Forward by Kelsey Hightower


If developers are the superheroes of the software industry, then the lack of documentation is our kryptonite.

Kelsey hightower

It’s four AM and your pager goes off. Your company’s service has crashed and clients are panicking. You scramble through a half-familiar code base, searching for the root cause. The error messages in the unit tests are frustratingly unspecific, and the internal README consists of headings followed by repeating one-word paragraphs: [TODO].

Or maybe your service is performing great and getting better. As more clients sign on, they have questions. So many questions. Emails and support tickets flood in as your service scales, and you’re increasingly pulled away from development and into support.

Most of us have to learn the importance of documentation the hard way, by finding it missing when we need it the most

Well-documented projects save time for both developers on the project and users of the software. Projects without adequate documentation suffer from poor developer productivity, project scalability, user adoption, and accessibility. In short: bad documentation kills projects. 

We found that documentation quality predicts teams’ success at implementing technical practices. These practices in turn predict improvements to the system’s technical capabilities, such as observability, continuous testing, and deployment
automation

Google 2021 Accelerate State of DevOps Report

Docs for Developers demystifies the process of creating great developer documentation, following a team of software developers as they work to launch a new product. At each step along the way, you learn through examples, templates, and principles how to create, measure, and maintain documentation.

Learn how to create documentation that makes you and your users more productive

This book does for dev docs what The Phoenix Project does for DevOps – It makes your aspirations attainable.

Anne Gentle, author of Docs Like Code

See the Table of Contents


Order your copy now!

Documentation for Developers is now available at your bookseller.

And, of course, you can request it from your local library!


Follow us on Twitter at @docsfordevs for more information about the book, sign up for RSS below, and follow our posts for more tips on writing great developer docs.


Posts

Book Launch Day!

You and your team can now buy, rent, or borrow a copy of Docs for Developers. Our team is so excited that this book is out for you to use and share! Our goal in writing this book is to scale our decades of technical writing experience out to the people who need it mostContinue reading “Book Launch Day!”

How to: Error Messages

A well-formed error message has the following elements: A unique identifier A short description of the problem A suggested remediation If you want to be really generous in your error messages, you can also give people a way to report the error from within the error message, or contact support. So how does that lookContinue reading “How to: Error Messages”

We wrote a book!

Eighteen months ago, a scrappy team of technical communicators got together to create what they (we) wanted to see in the world — an approachable book about creating technical documentation for the developers we know and love. There are a lot of times that it isn’t possible to hire a dedicated writer, but that doesn’tContinue reading “We wrote a book!”