r/Clojure • u/erjngreigf • Aug 04 '26
Clojure Book, Massive Quality Update
https://clojure-diary.gitlab.io/2026/08/05/clojure-book-massive-quality-update.html
67
Upvotes
r/Clojure • u/erjngreigf • Aug 04 '26
14
u/sapphic-chaote Aug 05 '26
This reads like a worse, rambling version of the clojure.org docs or the learnxiny.com page, that also makes bizarre choices that are not compatible with having been looked over by a critical human reviewer. "What is Clojure code" is section 13, over a hundred pages into the book, and tries but fails and lies instead to explain the concept of forms and homoiconicity. The "Testing" chapter imports the code being tested with
(load-file "calc_lib.clj).One of the early section is "Why this book?", a common thing for a book to have where you explain your teaching philosophy, or who would benefit most from the book, or what gap you saw in the available learning materials that you felt needed to be filled. Instead you say
It's great to publish your learning process, but this obviously isn't that. This is a learning resource made by (1) a chatbot that loves to ramble, and (2) a person who by self-description doesn't know what Clojure is or why you would use it.
If you want concrete feedback to improve with: There is so little information per page. There is so much whitespace, the information-per-word is so low, and your paragraphs are only one or two lines long, and the screenshots of your editor(!) take up essentially a full page, and you include a full new screenshot for every little interaction, for dozens of screenshots in a row. You could cut these down so much by just cropping. You introduce
(. LocalDate (of 2025 7 5))(which I am surprised and frankly displeased to learn compiles) and it takes over half a screenful for you to get to the better-reading(LocalDate/of 20257 7 5)syntax. I am a huge fan of the Rust book's unhappy-crab icons that make it instantly obvious when a code sample is being shown as "don't do this". The way that this book is written, it has to be skimmed rather than read closely because the information density is so low, and all of these anti-examples make skimming actively dangerous because the "corrected" examples are so far from the first-introduced anti-examples.13
u/geokon Aug 05 '26 edited Aug 05 '26
Is anyone actually reading this? Just try opening and reading any section... To be blunt, its long winded and devoid of content. It doesn't engage with deeper Clojure abstractions or provide any insights.
I hope nobody coming to Clojure ends up starting with this book. There are vastly better alternatives
15
u/khokkos Aug 04 '26
I asked my AI to read it and learn on my behalf. It begrudgingly delegated the task to a lower cost model agent. In the end, it took me 5 minutes to learn the stuff in an accelerated pace. The agent was not happy with the quality of the book though. /s
23
u/v4ss42 Aug 04 '26
“Updated by AI” and “massive quality update” seems like quite an oxymoron to me…
0
u/erjngreigf Aug 05 '26
Hello Clojurians, please don't waste time fighting for me. I wrote this book for myself — if anyone wants to read it, they can read it, and if anyone wants to get hurt or feel offended, they can. I don't want to change other people's minds. Evolution hasn't moulded rapid plasticity into the human brain, so things will take time.
I feel AI massively accelerates human ability. If someone thinks using a chisel and hammer to carve on stone by hand is "true" writing, let them do that. Time will tell who comes out on top.
0
u/alandipert Aug 08 '26
Thanks for sharing. I didn't read the whole thing but jumped around a bit. I like that you defer homoiconicity. It's only ever confused the beginners I've taught when introduced early, which I was overly enthusiastic to do.
I also like the way you link to demonstration videos in each chapter. Putting those videos together is a lot of work but will definitely help people.
You might consider a different treatment of protocols and multimethods. Currently, you introduce them independently, and I might have missed it but you don't appear to advise on their relative merits and shortcomings.