Migsar Navarro
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 loved the book, I definitely recommend it to any one interested in mind and conscience.
I think it has a lot of information and good references, even for books that the author has not yet read but might be interesting. I don't think the reader should agree with anything stated on the book to profit from it, it is mentioned several times that some things in the field are just recently being discovered.
I had a few eureka moments while reading the book, one of them was about the path to result usually not being the shortest path, considered being the result of two independent quests, let's say you want to go from A to C, not caring about traversing B, paths from A to B and B to C are optimized independently and use the shortest path, but then there is a shortest path from A to C, but it is more efficient, in terms of effort, to take what you already have and do A to B then B to C than to invest a lot of resources in the more efficient A to C.
It offers some interesting categorizations, not all of them attributed to the author, the two I remember are:
- Creatures by kinds of intelligences: Darwinian, Skinnearian, Popperian and Gregorian.
- Pedro Domingos' five tribes of ML: Symbolists, Connectionists, Evolutionaries, Bayesians and Analogizers.
By the end of the book I had two important disagreements, more of the kind of misunderstandings. He mentions that even if he believes in hard AI he does not think is feasible for now, I think it is feasible, although I partially agree with him on not being appealing (I think it is a matter of perspectives and marketing, not effort). Then he compares termites and humans and say it is obvious that humans are superior, I think we are superior, by some criteria, but he felt in the trap he described along the book about taking an anthropocentric perspective, not a big deal but can be misleading for people only reading the conclusions or taking that from the book.
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.
It was not what I expected, the book is very opinionated and biased against AI and machines. I didn’t expect her to be completely neutral, that would be really hard for any of us being humans but I did expect her to be a bit more fair given the fact she decided to write about this topic. It is not very technical but more of a moral reflection about modern world’s algorithmic tools, and as a consequence it is more appealing to people that share some common background with the author.
The book is divided in seven field chapters: Power, Data, Justice, Medicine, Cars, Crime, Art, and a conclusion chapter to close. I think there is a lot of overlapping among some of the chapters and others may not be as relevant. Through the book the author presents a lot of factual information about news and studies related to the algorithms in that field, but most of those are not new but the same ones that you can find in other popular books about algorithmic biases(I am thinking in Weapons of Math Destruction here).
I was really disappointed by the last chapters, and particularly the conclusion which I would summarize as a conservative call to regulate algorithms for the sake of humanity, understanding humanity not as a scientific feature but a spiritual one. Still I am trying to be fair, since the opinion part should be assumed from the How to be human in the age of the machine part in the title.
Nevertheless, and precisely because it is this lack of empathy she criticizes from algorithm makers and adopters, she should have tried to think that not all human share the same background and experiences regarding this topic are vastly influenced by geography, which is not just development indexes and access to the technologies but also the culture and social norms used to assess the outcome (just to be crystal clear, I don’t think algorithms are fair, I think humans are at least as unfair as algorithms because they are designed by them, a topic that is briefly discussed in the book but apparently vanished from the conclusions).
I won’t say the book is bad, most of it is interesting and well written, but I disagree with the reviews, and wouldn’t call it a science book or say it explains AI, machine learning or complicated algorithms. Although I enjoy it I would have not picked it, or said another way, I would have spent my time reading another book. I’ll let here two quotes that I hope will help you decide if it is the book for you.
But for me, true art can’t be created by accident. There are boundaries to the reach of algorithms. Limits to what can be quantified. Among all of the staggeringly impressive, mind-boggling things that data and statistics can tell me, how it feels to be human isn’t one of them.
The supermarket algorithm that robs a teenage girl of the chance to tell her father that she’s fallen pregnant.
I really enjoyed the book and I would definitely recommend it to others. I actually have been actively trying to get more people to read it.
The book demystifies big data and statistics and raise awareness about the topic, through the chapters Cathy shows how deeply intertwined it is with public policies and day to day opportunities like buying a car or an apartment, getting affordable and good education for you or your children, even being stop by the police on the sole premise of ethnicity.
I think this is a good first book about the subject, most of the data is from US and a bit from Europe but consequences are global so it would be great to have more data from other countries as well.
I was expecting more from the book, I have no doubt the author is an excellent history lecturer but I do not agree at all on his philosophical points of view. Most of the book is speculation and what he thinks given his cultural context can happen in the future. About the reference to states and/or nations I think he fails to give a full panorama by not openly acknowledging Israel facts, it criticize some nations and “empires” a lot but barely mentions related facts in which Israel participated.
The historical knowledge is solid but I don't think is the best source to get to know latest trends about philosophy of mind or consciousness, the book can be misleading in this regard because quotes in a context end up being opinionated, and being the theme of the book mankind future I think this is a critical negative aspect.
I would not recommend to read it, if you or a friend happen to have it, it is ok, narrative is not bad at all and there are some interesting references to follow up in the bibliography.
P.S. I would actually use small sections of the book to foster discussion on young students, I think it would be very formative for considering some aspects of history not always address on school books.
I've been wanting to read this book for a long time. It is good, I like it and find it very interesting but I think it is a philosophical introspection wrapped in a science fiction book. It goes through many different life philosophies and discussed them from a first person point of view, I think the spectrum is far from complete and the book portraits not the best aspects of each doctrine. The book is about the journey of discovery of a human being framed in a post-apocalyptic underground world and is a very interesting approach to the comfort versus knowledge dilemma.
I would definitely recommend it but I doubt I will ever read the following books in the series.
Amazing book, it is a bit hard to read at times, specially the first chapters because the huge quantity of facts and data presented, but it completely worth it, I learned so much and enjoyed the whole book.
I would recommend anyone to read the last chapter if you are only going to read one chapter, it gives great context to understand some current world issues and distribution.
It is a good book, it is about Portugal's naval/maritime history in the age of exploration. It is enjoyable and readable for foreigners, as it is written in a clear and concise way. Sometimes it is a bit subjective about some characters and political significance but not in a non-polite or rude way.
I really love this book. I read some reviews about not being technical enough but I think, that is stated on the cover and the back cover. Nevertheless I think it offers a good introduction about the subject with some insights about the chronological order and the reasons for that order. Sometimes it feels a little off-topic but I think that gives a more personal feeling to the book and makes easier to relate it to the person who is living it.
Gran libro. Creo que da una nueva perspectiva respecto a los motores de la evolución humana, es bien sabido que se necesita un exedente en la producción para el desarrollo de las artes pero me parece muy sensato asociarlo también al desarrollo de la sociedad en general. La teoría de las latitudes y la importancia de factores como el grado de desarrollo al llegar a un nuevo territorio y las especies nativas del mismo como pilares para entender las posibilidades de un grupo humano me parecen también ideas fundamentales que se logran expresar clara y sencillamente en este libro.
I really like how Steven Pinker writes, even if the topic of the book is really technical he knows how to make it easy to understand and keeps you interested because of all the facts he gives.
After reading this book you won't ever think about language in the same way, you'll notice that there is no correct language and it is an ever-evolving living subject, the so called mistakes are sometimes a logically better approach to language and that is why most kids repeat them. This book also gives a clear insight on how the human brain is structured because language is a central part of our everyday lives.
Este libro cambio mi forma de pensar acerca de la ciencia. Muchas veces se cree que es un camino con una meta definida en donde cada descubrimiento es un escalón en una escalera que nos acerca, sin embargo, se trata de una labor que siempre debe de ser analizada dentro de un contexto histórico, pues, como todas las cosas humanas, depende del cristal con que se mira, existen tiempos estériles, etapas obscuras, procesos que deben de llevarse a cabo antes de que sea posible dar el siguiente paso. Creo que Thomas Kuhn hizo una labor excelente al escribir este libro pues el análisis del proceso es necesario para entender el estado actual de las cosas e intentar definir un estado futuro favorable.
I bought this book because of the title and the cover's photo, also because I've heard of the author but I have to tell that I'm really disappointed, it was not that bad while I was reading but it was because I was expecting something more before the book ends and after I finished it I felt like I was reading some kind of preface not a book by itself.
When I first start reading it I thought it was boring and tedious but after a few chapters I started to enjoy some of the descriptions, I wouldn't recommend it as a must-read book, but I think its interesting for analyzing the way of thinking of a certain Mexican upper-class with academic aspirations (as far as I know). Being Mexican there are a lot of things that I don't like about politics and education in Mexico and I think that reading this book is a nice way to discover most of them, as he points out in some part of the book, “no one likes it but that's the way it goes” sadly most of the time its true.
I do like the approach it takes to Cuban culture, specially music and literature, I think it's a friendly way to known a little bit about Cuba, maybe it could be considered too superficial but I think that is what makes it a good first contact to the culture, and if someone is interested can get a full list of authors and books from the last century along with a good idea of some of the main characteristics of each author.
El inicio del libro no me gustó en lo absoluto, tanto sentimiento como lenguaje, vacío y soso, sin embargo, poco a poco fue tomando un matiz divertido, no me parece una narración envolvente ni amena, pero sí entretenida, incluso se me antojó ir a formar mi propia opinión de varios de los lugares mencionados... en fin, no podría decir que lo recomiendo pero al terminar me gustó lo suficiente como para darme otra oportunidad de leer algo suyo.
No me gustó este libro porque me parece que promueve muchos prejuicios y estereotipos ya bastante fuertes en la cultura mexicana. Como casi todo libro, tiene algo rescatable, la narración no es mala y las algunas descripciones son realmente emotivas, sin embargo, me da tristeza que se pierda todo esto en una narración absurda que pretende despertar sentimientos neo-nacionalistas. Creo que es en gran parte una teoría sobre metafísica, conspiraciones y mundos imaginarios.
Me parece que se tiene que superar la ya trillada lucha por rescatar un glorioso pasado indígena, creo que se debe de aceptar y conocer la historia, sobre todo la propia, pero no intentar enaltecerla con esta clase de historias porque el resultado es el contrario. Aunque a mí no me gusto el libro no intento decir que no se lea sino que se lea con criterio.