[dilap]

I noticed that a lot of the documentation seems to combine "how this works" with "why this works the way it does"; the why is great when you're interested in diving deeper, but it's frustrating when all you're interested in is the how.

For example, the linked blog post spends a lot of time talking about diamond dependencies and other package managers. This is just noise that gets in the way when you're trying to figure out how does this work?

If you did want to combine both in a single reference doc, I would move the why out into separate, skippable sections.

When I first was learning Go, I was really impressed by how easy it was to understand the language just by reading the spec. I've found the opposite to be true for Go modules. (Which also, as near as I can tell, doesn't have a spec, but just various scattered blog posts, for various different iterations of the idea.)

[deklerk]

Thanks, this is good feedback. In general, I reckon having a variety of documentation is great, so also would like more of "how" documentation.

I believe the tutorials that are in the work take more of the "short and sweet" approach, which should help with this.

[justicezyx]

Googlers tend to explain "why" of their decisions.

I'd suggest just taking the advises and decide the best course of actions. The why part is generally only meaningful to the decision maker and not something people care or have enough context to appreciate.

This way a lot of potential misunderstanding was avoided.

[_y5hn]

"Why" is context for learning.