Docs for Developers
Ratings5
Average rating3.1
15
Ratings5
Average rating3.1
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.
Reviews with the most likes.
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.
