Jared Bhatti - Docs for Developers: An Engineer’s Field Guide to Technical Writing

This Apress imprint is published by the registered company APress Media, LLC part of Springer Nature.

The registered company address is: 1 New York Plaza, New York, NY 10004, U.S.A.

If a new software project is created and there are no docs around to learn it, does it work?

Most of your potential users will never know because theyll never find your project, and if they do, theyll have no clue how theyre supposed to use it. This is an all too common problem, and as a software developer myself, I can honestly say I spend too much of my time reverse engineering command line tools, libraries, and APIs that lack adequate documentation necessary to complete the task at hand.

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

This is what we call the developer loop, and the most successful projects have documentation to guide developers through each of these steps. Its because documentation is a feature. In fact, its the first feature of your project most users interact with, because its the first thing we look for when trying to solve a problem.

So it begs the question, why is documentation often deprioritized or missing altogether?

Its not because were not invested in it, nor is it because we arent good writers. Its because many of us dont know how to do it. Its because we, as developers, rarely understand that in addition to the developer loop, theres an equally important writer loop.

The writer loop is similar to how we write code. It requires you to understand the problem your users are trying to solve, create a plan for solving it, use common design patterns, and write the content that solves the issue. The developer loop and the writer loop are two sides of the same coin. During the writing loop, were creating information our users want during the developer loop. Knowing how to bring these two loops into alignment helps both your project and your users succeed.

I realized this myself when introducing new developers to Kubernetes. Developers wanted to know how all the pieces of Kubernetes fit together, but there wasnt any content that helped them. I found out quickly that you have about five minutes to help developers find the information they need before they abandon your project and move on to something else.

Thats what led me to write Kubernetes the Hard Way, a hands-on approach that now has over 27,000 stars on GitHub. Likewise, when developers were seeking information on how to quickly get Kubernetes up and running for their infrastructure, I worked with co-authors to write the aptly named book Kubernetes: Up and Running.

Through these experiences, I learned more than I ever wanted to know about the writer loop and how necessary it is to developers. Thats why I was excited to learn about this book.

The authors of this book have worked on documenting several difficult technical projects at places like the Linux Foundation, Google, Stripe, LaunchDarkly, and the UK government, working to meet developers needs through documentation. In this book, they distill their experience into a step-by-step process that you can apply to any project, along with case studies, tutorials, and tips based on hard-won experience.

So, here it is: The book youre holding guides you through the phases of the writer loop by leveraging real-world situations and a workflow that is so pragmatic and effective that Ive been using parts of it over the years and didnt even know it.

Add documentation is a step in every product release plan, and we need more docs is an action item from every internal developer productivity survey, but its surprisingly difficult to translate those concise goals into useful documentation. Docs for Developers reveals the repeatable process behind incredible documentation.

Will Larson, CTO at Calm, author of An Elegant Puzzle and Staff Engineer

Great documentation is an often overlooked yet critical component for ensuring the success and large scale adoption of a software project. Docs for Developers is a must-read for developers and technical writers who want to rapidly accelerate their ability to create documentation that is easy to consume, brings joy to end users, and is capable of dramatically improving business results.

Brad Topol, IBM Distinguished Engineer, Open Technology and Developer Advocacy. Co-author of