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].

Who wrote this, you wonder. With a sinking feeling, you realize you’re looking at your own code from fourteen months ago, and you’ve forgotten almost everything about it.

You search your memory for any reminder of what you were doing, why you did it this way, and whether you’d peer-reviewed or tested for a particular set of edge cases. Meanwhile, your clients open support ticket after support ticket, demanding answers.

Your own words come back to haunt you: the code is self-documenting.

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.

As the person most knowledgeable about what you’ve built, you’re doomed to a calendar full of one-on-one support meetings, answering the same question from six different people. You know you could fix the problem if you had an opportunity to research and write down how things work, but you’re so busy replying to users’ questions that you never have the time.

Now picture another scenario: your code is commented and your READMEs are accurate and up to date. You have a getting started guide and a set of tutorials that target your users’ top use cases. When a user asks you for help, you point them to documentation that’s genuinely helpful. That four AM pager alert? It took five minutes to resolve because you found what you needed with your first search.

Effective developer documentation makes the last scenario possible.

You might have heard the often-misquoted saying that good code documents itself. It’s true that good naming, types, design, and patterns make code easier to understand. But projects with sufficient complexity and scale (that is, most projects worth building) need human-readable documentation to help others quickly understand what you’re building and how to use it.

The authors of this book have helped a number of organizations create great developer documentation, including large tech companies, fast moving startups, government agencies, and open source consortiums. We each have years of experience creating developer documentation, listening to and working with developers, and generally being immersed in every aspect of developer docs at every scale.

We’ve helped innumerable developers out of the nightmare scenarios described above. The more we helped, the more we realized that there wasn’t a primer for developers looking to create documentation. So, we went to work, documenting a fix to the problem we observed developers experiencing.

We created this field guide to technical documentation by building on our own expertise and feedback from a multitude of developers. It’s designed as a resource to keep at hand, so you can write documentation as part of your software development process.

This book walks you through creating documentation from scratch. It begins with identifying the needs of your users and creating a plan with common patterns of documentation, then moves through the process of drafting, editing, and publishing your content. The book concludes with practical advice about integrating feedback, measuring effectiveness, and maintaining your documentation as it grows. Each chapter builds sequentially on previous chapters, and we recommend following the book in order, at least on your first read through.

Throughout this book, we weave through stories about a developer team working on a fictional service called Corg.ly. Corg.ly is a service that translates dog barks into human language. Corg.ly uses an API to send and receive translations, and uses a machine learning model to regularly improve its translations.

Finally, this book is intentionally agnostic about tools and frameworks. It may seem frustrating that we don’t tell you to write in a particular markup language or publish with a particular static site generator that automatically updates with a particular continuous integration tool. Our opacity is intentional: the languages and tools that work best are the ones closest to your own code and tooling.

If, by the end of this book you’re still looking for more guidance on tooling, we provide an appendix of resources you can use to find additional information and the right documentation tools for your needs.