I’m writing a guide for somewhat experienced developers on how to start writing your own API with clojure. (i’ll post it here on clojureverse when finished)
And i didn’t wanted to explain what is a namespace, i made it a pre-requisite in order to read my guide, but i wanted to link some explanation, and i googled “clojure namespaces” and the first link was clojure.org explanation on namespaces: https://clojure.org/reference/namespaces
Well, let’s take a look at the first lines:
Namespaces are mappings from simple (unqualified) symbols to Vars and/or Classes. Vars can be interned in a namespace, using def or any of its variants, in which case they have a simple symbol for a name and a reference to their containing namespace, and the namespace maps that symbol to the same var.
I think this is atrocious for newcomers or even experienced developers, because it’s talking about too specific things. Shouldn’t we stop and think a little more about those references in the main place where people would look for understanding something about clojure?
P.S: i ended up referencing a chapter on Clojure for the brave and true as the resource to learn about namespaces