[jampa]

Thanks for this post. As someone writing an open-source book (without an editor to help), I find some takeaways very helpful.

But I think your most significant change was changing the "what" to "why".

Reading the original, we can see that most sentences start with "we did..." "we did..." and my impression as a reader was, "Okay, but how is this important?" In the second one, the "what" is only in the first part of the sentence, to name things (which gives a sense of novelty), and then only "whys" come after it.

"Whys" > "Whats" also applies to good code comments (and why LLM's code sometimes sucks). I can easily know "what" the code does, but often, I want to know "why" it is there.