Migsar Navarro

Great book to learn a bit about developmental psychology. I really loved the way it presents information and the baseline idea that babies and scientists are alike.

Excellent book. I loved the way it is written, concise and easy to read.

I would recommend this book to anyone that takes software development seriously. I have read a few comments mentioning that it talks too much about comments, but I disagree with those and agree with the author, comments are very important and it is really hard to write clear, effective and useful comments.

I would say that a chapter on code reviews is missing, following the same line of thought that for comments, I think code reviews are not easy to do or obvious. Bad code reviews can make a project fail and I know some people will disagree but in my opinion, software design is way more than code.

Excellent book. The ideas and concepts presented are very interesting, useful and fact supported. Even if I don't agree with some of the conclusions, particularly the ones regarding social and political issues (I know, most of the book), I think it is a great starting point.

Not the kind of books that I usually read but it was ok, I think I learn a few things from it.

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.