What do you think?
Rate this book
Docs for Developers: An Engineer’s Field Guide to Technical Writing
Learn to integrate the craft of writing with the craft of programming. This book teaches you how to create documentation for each step in the software development lifecycle, from understanding your user's needs to publishing, measuring, and maintaining useful developer documentation.
A well-documented project saves time for both developers on the project and users of the software, and projects without adequate documentation suffer from poor developer productivity, project scalability, user adoption, and accessibility. In short: bad documentation kills projects.
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, which you can adapt to the needs of your own organization.
What You'll Learn
Create friction logs and perform user research to understand your user's frustrations Research, draft, and write different kinds of documentation, including READMEs, API documentation, tutorials, conceptual information, and release notes Define an information architecture for a larger set of documentation, optimized for search Publish and maintain documentation alongside regular code releases
Measure the success of the content you create through analytics and user feedback
Who This Book Is For
Ideal for software developers tasked with creating documentation alongside code or for technical writers, developer advocates, product managers, and other technical roles that create and contribute to documentation for their products and systems. Technical managers will also find value in adapting their teams or organizations to improve software documentation practices.
A well-documented project saves time for both developers on the project and users of the software, and projects without adequate documentation suffer from poor developer productivity, project scalability, user adoption, and accessibility. In short: bad documentation kills projects.
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, which you can adapt to the needs of your own organization.
What You'll Learn
Create friction logs and perform user research to understand your user's frustrations Research, draft, and write different kinds of documentation, including READMEs, API documentation, tutorials, conceptual information, and release notes Define an information architecture for a larger set of documentation, optimized for search Publish and maintain documentation alongside regular code releases
Measure the success of the content you create through analytics and user feedback
Who This Book Is For
Ideal for software developers tasked with creating documentation alongside code or for technical writers, developer advocates, product managers, and other technical roles that create and contribute to documentation for their products and systems. Technical managers will also find value in adapting their teams or organizations to improve software documentation practices.
252 pages, Kindle Edition
Published September 30, 2021
Ratings & Reviews
Friends & Following
Create a free account to discover what your friends think of this book!
Community Reviews
Displaying 1 - 22 of 22 reviews
December 16, 2021
I am very interested in improving my own writing and documentation skills, for my own product development needs as well as my client consulting needs. I had high hopes for the book but it did feel kind of basic. It is also very focused on API documentation and while I find that interesting I am also interested in the needs of closed source project docs for internal teams, not only documenting the code but how technical decisions were made, possibly using things like Architectural Decision Records.
It's not a bad book but did not fully cover what I was looking for.
There are a bunch of resources listed at the end that I hope to get into next.
It's not a bad book but did not fully cover what I was looking for.
There are a bunch of resources listed at the end that I hope to get into next.
March 27, 2022
This book started off strong but fizzled out really fast. The first few chapters were interesting but everything else wasn’t all that necessary.
Documentation is great. I agree with that. I’ll always encourage it. We should 100% document more.
The book is at its best when it’s showing you templates as they relate to the concepts at hand. This is great and worth 4 stars.
It’s at its worse when you start reading it and it feels like they’re talking about maybe one very company specific issue they’ve faced. For example, I could probably relate this to working with a data science project but it wouldn’t be because of the book itself because most things here are dealing with simple API work. Should this book cover all cases? Absolutely not. But for the sake of relatability, they shouldn’t have tried to make everything so web dev centric. Them doing that makes it seem like they don’t understand the essence of documentation outside of knowing we should write and maintain it.
So let’s say we remove the web dev examples and the fictional company/product and only work on the core. What do we have left?
We have a 3-4 part Medium article.
This book should’ve taken its own advice and picked the right tools for the job. This book has nice templates that we can’t use because it’s in book form and thus reminds me of a part in the book where they talked about making sure executable code could be copy pasted so users can use it. Are templates not executable bits of logic?
This book has a lot of link resources showing they’ve done their work. They also mentioned saving links for the end of documentation so that users could click through them if they wanted to learn more. They mention this but I’m not able to do this unless I type out a URL.
There are other moments in this book that have me wishing it was just a blog post so I could actually interact with the information they’ve given me. This then makes me think that they don’t understand their audience here.
This isn’t a book/resource discussing theory or anything low level as it relates to documentation. This is a show and tell. A very high level book that talks about documentation and how to write/edit/publish it. It doesn’t move the needle on the topic. It just shines a light on it. If all we’re doing is shining a light on documentation then why not post this information through a medium where most people looking for overviews are more likely to see it? I feel like if someone isn’t writing (this is implied by the sections that teach you how to brainstorm and organize thoughts) then they probably aren’t investing enough time into reading. If they aren’t investing enough time into reading then they probably aren’t buying books.
So who is this book really for? If someone is in the habit of buying books to understand these topics then could we not assume that they would already know how to document on a high level? Because none of this information is new. None of it. And I don’t read anything on documentation so imagine those who actually study the topic? This book isn’t for them.
And I’d imagine that someone just getting into this topic would probably run into more tutorials and blog posts online before they even got to this book, unless this book was recommended.
So I ask again…who is this book really for?
Documentation is great. I agree with that. I’ll always encourage it. We should 100% document more.
The book is at its best when it’s showing you templates as they relate to the concepts at hand. This is great and worth 4 stars.
It’s at its worse when you start reading it and it feels like they’re talking about maybe one very company specific issue they’ve faced. For example, I could probably relate this to working with a data science project but it wouldn’t be because of the book itself because most things here are dealing with simple API work. Should this book cover all cases? Absolutely not. But for the sake of relatability, they shouldn’t have tried to make everything so web dev centric. Them doing that makes it seem like they don’t understand the essence of documentation outside of knowing we should write and maintain it.
So let’s say we remove the web dev examples and the fictional company/product and only work on the core. What do we have left?
We have a 3-4 part Medium article.
This book should’ve taken its own advice and picked the right tools for the job. This book has nice templates that we can’t use because it’s in book form and thus reminds me of a part in the book where they talked about making sure executable code could be copy pasted so users can use it. Are templates not executable bits of logic?
This book has a lot of link resources showing they’ve done their work. They also mentioned saving links for the end of documentation so that users could click through them if they wanted to learn more. They mention this but I’m not able to do this unless I type out a URL.
There are other moments in this book that have me wishing it was just a blog post so I could actually interact with the information they’ve given me. This then makes me think that they don’t understand their audience here.
This isn’t a book/resource discussing theory or anything low level as it relates to documentation. This is a show and tell. A very high level book that talks about documentation and how to write/edit/publish it. It doesn’t move the needle on the topic. It just shines a light on it. If all we’re doing is shining a light on documentation then why not post this information through a medium where most people looking for overviews are more likely to see it? I feel like if someone isn’t writing (this is implied by the sections that teach you how to brainstorm and organize thoughts) then they probably aren’t investing enough time into reading. If they aren’t investing enough time into reading then they probably aren’t buying books.
So who is this book really for? If someone is in the habit of buying books to understand these topics then could we not assume that they would already know how to document on a high level? Because none of this information is new. None of it. And I don’t read anything on documentation so imagine those who actually study the topic? This book isn’t for them.
And I’d imagine that someone just getting into this topic would probably run into more tutorials and blog posts online before they even got to this book, unless this book was recommended.
So I ask again…who is this book really for?
October 1, 2022
Es una muy buena guía sobre el proceso de escribir documentación clara y útil para tus usuarios finales, pero me faltó más guía de cómo escribir documentos internos o documentación técnica a nivel de código para que otros desarrolladores puedan retomar el trabajo, pero creo que estos principios pueden ser muy aplicables también pare ese tipo de documentos.
Básicamente es aplicar el mismo proceso de UX y DevOps/Release que se aplica a los productos a la documentación y ponerla como un producto importante, de primer orden.
Te guía a través de todos los pasos necesarios para crear buena documentación, desde descubrir por por qué la creas hasta el proceso de reemplazarla y eliminarla cuando no se necesita.
También da consejos muy útiles sobre cómo escribir claramente, qué es un documento de calidad, qué se espera en general de la documentación y recomendaciones sobre herramientas y cuánto contratar a alguien más especializado.
Creo que es un libro que todo equipo de desarrollo debe leer, para mantener en la mente la importancia de crear y mantener buena documentación, ya que deja clara una lección importante: un programa, por muy bueno que sea, si nadie sabe cómo usarlo, no sirve.
Básicamente es aplicar el mismo proceso de UX y DevOps/Release que se aplica a los productos a la documentación y ponerla como un producto importante, de primer orden.
Te guía a través de todos los pasos necesarios para crear buena documentación, desde descubrir por por qué la creas hasta el proceso de reemplazarla y eliminarla cuando no se necesita.
También da consejos muy útiles sobre cómo escribir claramente, qué es un documento de calidad, qué se espera en general de la documentación y recomendaciones sobre herramientas y cuánto contratar a alguien más especializado.
Creo que es un libro que todo equipo de desarrollo debe leer, para mantener en la mente la importancia de crear y mantener buena documentación, ya que deja clara una lección importante: un programa, por muy bueno que sea, si nadie sabe cómo usarlo, no sirve.
June 8, 2022
This is very concise book for learning how to write and structure effective documentation as a developer. The book uses a fictional company’s product as a way to put theory into practice, by providing implementation examples along the journey. I found the book highly enjoyable and easy to read, it completely fulfill it’s purpose of introducing the reader to the world of documentation and provides references to dig a bit deeper if you are interested.
I’ll definitely recommend this book to my developer friends. Still, there are two notes that I consider important to know before reading it. The first one is about the perspective when writing documentation, it is commonly assumed that documentation is targeted for customers or external users, I believe this case will continue to exist but it will be increasingly common to have a need for internal documentation as we become aware of its benefits. The book mentions once or twice that documentation can be internal as well, and all of the content will hold true for internal documentation, but it is clearly written with external users in mind. Probably it is this way because customers would be part of any business plan and their needs are a fundamental part of any business being profitable, so those are very visible for executives, I would say internal documentation can have an impact as big for a company if done right because it can greatly improve efficiency, significantly reduce the time to market for new features, and as an added bonus, increase developers happiness.
A document is good when it fulfills its purpose.
In my opinion the book should start with the quote and probably with chapter 9, the one including it. It is not a quote from the authors but a quote quoted from another publication, still I think it is of uttermost importance when writing documentation, to answer the question: what for? And that is what my second comment is about, I would structure the book in a little different way. I think it would be super nice to have a TLDR; convention for books, but until that happens, I think one of the hardest parts of writing an educational book is to know in which order present the topics because you never know what readers will read.
I don’t consider the actual ordering to be bad, since it is a very hands-on approach, but from experience I would say it is often a good idea to slow down a bit and consider costs, in terms of effort, time and money, beforehand. So I would move the last three chapters to the beginning of the book. The audience depends on the purpose and the purpose often become very clearly defined when you try to measure quality, because, as the quote express, those are intrinsically related. Once you have an idea of the purpose and therefore the audience and the metrics you can think about the structure of the documentation, not from the writer point of view but from the consumer, and get a roughly estimate of the cost it will take to produce it, including the cost and effort to maintain, which is medium and long term and as a consequence easy to miss in all the excitement of joining a new initiative.
I often hear people saying that if it is needed it must be done no matter the cost, or even better, disregarding the cost, which often means not being fully aware of it. I find that a naive affirmation, and as it is stated in the book and in many other places, poor documentation is worst than no documentation.
I’ll definitely recommend this book to my developer friends. Still, there are two notes that I consider important to know before reading it. The first one is about the perspective when writing documentation, it is commonly assumed that documentation is targeted for customers or external users, I believe this case will continue to exist but it will be increasingly common to have a need for internal documentation as we become aware of its benefits. The book mentions once or twice that documentation can be internal as well, and all of the content will hold true for internal documentation, but it is clearly written with external users in mind. Probably it is this way because customers would be part of any business plan and their needs are a fundamental part of any business being profitable, so those are very visible for executives, I would say internal documentation can have an impact as big for a company if done right because it can greatly improve efficiency, significantly reduce the time to market for new features, and as an added bonus, increase developers happiness.
A document is good when it fulfills its purpose.
In my opinion the book should start with the quote and probably with chapter 9, the one including it. It is not a quote from the authors but a quote quoted from another publication, still I think it is of uttermost importance when writing documentation, to answer the question: what for? And that is what my second comment is about, I would structure the book in a little different way. I think it would be super nice to have a TLDR; convention for books, but until that happens, I think one of the hardest parts of writing an educational book is to know in which order present the topics because you never know what readers will read.
I don’t consider the actual ordering to be bad, since it is a very hands-on approach, but from experience I would say it is often a good idea to slow down a bit and consider costs, in terms of effort, time and money, beforehand. So I would move the last three chapters to the beginning of the book. The audience depends on the purpose and the purpose often become very clearly defined when you try to measure quality, because, as the quote express, those are intrinsically related. Once you have an idea of the purpose and therefore the audience and the metrics you can think about the structure of the documentation, not from the writer point of view but from the consumer, and get a roughly estimate of the cost it will take to produce it, including the cost and effort to maintain, which is medium and long term and as a consequence easy to miss in all the excitement of joining a new initiative.
I often hear people saying that if it is needed it must be done no matter the cost, or even better, disregarding the cost, which often means not being fully aware of it. I find that a naive affirmation, and as it is stated in the book and in many other places, poor documentation is worst than no documentation.
October 7, 2022
If you're starting in IT, you haven't read through documentation of several projects and you're suddenly tasked with preparing documentation for an open source library or a software, this is the book for you. It will give structure to the process by presenting a very reasonable set of steps.
Good high-level overview. But not enough explanation on how to actually perform these steps. Very few examples.
Good content. But bloated to hit 200 pages. Could be edited into a 10-50 pages primer without any losss. I wouldn't mind reading 200 pages about it if it wasn't all headers, introduction and summaries.
There is nothing there about writing style (like in "Elements of Style"), and not much about writing in general.
The most valuable part were numerous footnotes referring to original sources: blog posts, other books. It's worth the time to study those.
Good high-level overview. But not enough explanation on how to actually perform these steps. Very few examples.
Good content. But bloated to hit 200 pages. Could be edited into a 10-50 pages primer without any losss. I wouldn't mind reading 200 pages about it if it wasn't all headers, introduction and summaries.
There is nothing there about writing style (like in "Elements of Style"), and not much about writing in general.
The most valuable part were numerous footnotes referring to original sources: blog posts, other books. It's worth the time to study those.
July 24, 2022
A pretty interesting book that's very focused on technical writing on APIs. There's some interesting parts that apply very broadly to any type of technical writing and writing in general but a lot of it is very much about creating a specific form of documentation that wasn't quite what I needed. The book is pretty succinct however so at least it's quick to read through but I was looking for more information on information architecture and perhaps some more examples on how to write for different users that may consume technical writing.
Overall there's probably something for anyone but it's also one of those book that can be skimmed through and to only consume what seems interesting to you.
Overall there's probably something for anyone but it's also one of those book that can be skimmed through and to only consume what seems interesting to you.
December 28, 2021
The focus of the book is on writing documentation for an imaginary public API but I find that most of the suggestions and recommendations apply to almost all types of software projects. It is a great starting point for anyone wanting to introduce documentation on their software projects, irrespective of the company, product and team size.
I'm no beginner to documentation on software projects, but this book will serve as a reference whenever I will have to evaluate and maintain existing documentation.
I'm no beginner to documentation on software projects, but this book will serve as a reference whenever I will have to evaluate and maintain existing documentation.
This entire review has been hidden because of spoilers.
January 10, 2023
A concise, useful, and rather delightful walkthrough of how developers can create and maintain a set of decent documentation. As a technical writer with 5+ years, I nodded along to most of the recommendations, and even learned something new. I especially appreciated the whimsical dog translation examples and Cowboy Bebop easter eggs. This is a great read for anyone in the profession looking to learn something new.
February 8, 2022
This is a great book on a quite unloved topic: creating and maintaining documentation.
It guides its readers through the complete process of documenting software, but is also applicable in large parts to writing in general.
It is a quick and easy read and I think every developer who is not working on their own should read it.
It guides its readers through the complete process of documenting software, but is also applicable in large parts to writing in general.
It is a quick and easy read and I think every developer who is not working on their own should read it.
January 19, 2022
Indeed a field guide for technical writing, really well structured, with lots of helpful hints and references. I can highly recommend this book to anyone trying to put together a decent technical documentation.
February 4, 2022
A different book than I expected. Goes really well over the process of writing and publishing docs for external developers. Not so much aimed at docs for internal developers (colleagues or team members).
October 21, 2022
No one actually likes writing documentation. It has always seemed like an unclimbable mountain. With this book and the way in which the reader is walked through the process, I will be looking forward to putting the ideas in practice and beginning the process of writing some documentation....
December 30, 2022
Best reference and guideline for documentation
This book gives comprehensive, straightforward and clear guidelines to produce, update and maintain better documentations. The authors presented a good starting point in developing documentations and guidelines.
This book gives comprehensive, straightforward and clear guidelines to produce, update and maintain better documentations. The authors presented a good starting point in developing documentations and guidelines.
January 3, 2023
Should be mandatory reading for every programmer, product manager or person that is code-adjacent.
There are probably better books on the topic. But, if so, they are surely quoted and referenced in this one. Which is why this is a great reference to have around.
There are probably better books on the topic. But, if so, they are surely quoted and referenced in this one. Which is why this is a great reference to have around.
May 5, 2024
The book targets technical documentation writers, not software developers. Yet, software developers should still read it.
As a software developer, I was always anxious when opening a blank page for documentation. I had many questions: What topics should I cover, and which should I exclude? How many details should I mention on the selected topic?
After reading this book, I have answers to all those questions. Documentation is no longer the most hesitated part of a project for me.
It also changed my understanding of abstraction in software development. Abstraction isn't just for increasing cohesion or decreasing coupling. You should use abstraction to simplify developers' interactions with your libraries and APIs.
As a software developer, I was always anxious when opening a blank page for documentation. I had many questions: What topics should I cover, and which should I exclude? How many details should I mention on the selected topic?
After reading this book, I have answers to all those questions. Documentation is no longer the most hesitated part of a project for me.
It also changed my understanding of abstraction in software development. Abstraction isn't just for increasing cohesion or decreasing coupling. You should use abstraction to simplify developers' interactions with your libraries and APIs.
October 13, 2021
Great resource for technical writing not only focused on a dev role.
December 3, 2021
If you're an engineer and stuck in the "more docs would be great, but how" state of being. Read this book.
May 19, 2022
Great book: very practical, engaging, and clear.
September 6, 2022
Some good tidbits and gems but most of what is talked about can be learned through the process of writing your own technical pieces and iterating on it.
Nevertheless, it’s a good overview.
Nevertheless, it’s a good overview.
September 24, 2022
Good book for keywords inspiration and structural thinking. Not too much detail or example though.
October 9, 2022
Overall a very well-put-together book, I will have to start putting it to good use when working on my future projects.
December 30, 2023
Great introductory book. It doesn't teach you how to do anything, but it outlines all the elements that you need to know, and then you can do your own research to dig into the details.
Displaying 1 - 22 of 22 reviews