Reading clojure docs is a PITA
Check for example this page:
https://clojuredocs.org/clojure.core/require
First of all, it looks like some badly formatted prose, definitely not as some technical document that is supposed to convey exact definitions.
But the looks is just one thing, the content is even worse:
“Loads libs, skipping any that are already loaded.”
Normally I wouldn’t pick on the very first sentence, but if you read the whole page, you know what you will not find?
You will not find out what “load” actually is and isn’t.
The very thing this function does you are already supposed to understand before you start using it. This is mind boggling .
Reading further at least we can find out what a ‘lib’ is, but by that time my brain is already flooded with the following expressions that I don’t understand: libspec, prefix list, common prefix, flag that modifies, ns macro. Sure, I have some intuitive feelings about all these, but more than a decade of programming taught me to not even try to listen to intuition when reading documentation because it just misleads me. So in order to understand the first paragraph I would have to google at least those five expressions and then follow each of them down the rabbit hole. And this is just the first paragraph.
Ok, I realize if I start googling before reading everything, I might start chasing explanations that are present on this page, so I reluctantly read further, writing down everything that is unexplained so far to me: named set, resources, classpath, Java package, sharing names. Also, how can a shared name locate the root directory of anything?
Let’s continue: classpath-relative, path-mapping, associated namespace (sounds like the mafia).
Right, so now I see that libspec, flags and prefix lists are also explained to some degree, this could’ve been an easily recognizable feature of this page with some human friendly formatting. Instead every time I want to read anything about either of these things, I have to look for the for seconds, trying to distinguish between the grey text on grey background, like I am playing some boring game made by bad A.I. I just want to know what require does. Well, now I know that require loads libs. Let’s google this.
So, there is this page https://clojure.org/reference/libs that is the first in the google search results, obviously way better formatted, humanly readable page. Not sure why clojuredocs exists if there is this nicely formatted documentation? Also, if there are multiple docs, if I find some differences, how to know which is the correct? If there are no differences, why the duplicated content?
Reading through the docs, stuff starts to clear up, but I still don’t know what loading is.
Let’s google that.
This time I actually write out the question, hoping that I get some stackoverflow or similar answer, because I am starting to run out of time and I am wishing for something that would raise less questions than how many it answers.
I don’t see relevant SO questions, but the first result is this page: https://clojuredocs.org/clojure.core/load
Not sure why not some of the nice docs, but I click and find out that the load function “loads code”.
For some moment I stare at the screen and contemplate if there is any reason to try to ask about this on the support channels. But because last few times I did that I got told to “RTFM” (not literally, they are nice people they talk down to you in a very eloquent way), I give up and decide that maybe another day I will try to understand this again.
