Technical Writing as Symbolic Logic: Clojure Intern Symbol
The Namespace system maintains global maps of symbols to Var objects (see Namespaces). If a def expression does not find an interned entry in the current namespace for the symbol being def-ed, it creates one, otherwise it uses the existing Var. This find-or-create process is called interning.
from http://clojure.org/vars#Interning, , by Rich Hickey
this is a example of sub-par technical writing. It tried to explain the term “intern” by side-effect. The heart of such problem, is that the writing is not a logic exposition. Since the author Rich Hickey is creator of Clojure, so that means he know how it works because he wrote the Clojure namespace system, then this means either he is sloppy here, or unable to write logical expositions, or that he doesn't care for such style.
Note: logical exposition takes specialized training. In essence, you are using English for symbolic logic. First of all, you must understand what's going on in terms of symbolic logic. Since code or computer programs are precise instructions, but they are not declarative logic as in most logic systems, so you need to be able to turn any procedural algorithm into symbolic logic. That is a very difficult task. This means, even if you wrote a program, you may not be able to explain it in a logical exposition, because you do not know how it works as a math system (math is declarative. math is “what”, programing is “how”. (even though lots functional programing language are “declarative”, but that's in a local context (as in constructing the steps of algorithms, not at the level of whole software).)).
Even if you know the symbolic logic form, but then you still need skill to turn it into a readable simple English.
(am being sloppy here and do not fully understand what am talking about)
The quoted documentation is lousy because, upon reading it, one will not be able to understand exactly what it means. (for example, test someone who don't know Clojure at all, or test on someone who know another lisp and ask him if there's any difference between clojure's concept of intern vs say Common Lisp or Wolfram Language.)
ok, here's a quick example of why it fails.
the paragraph starts with “The Namespace system maintains …”. So, it states that X maintains something. It doesn't specify if the “maintaining” is all there is to X, or that X (the namespace system) does something else too. The “maintaining” is itself fuzzy. What does “maintaining” mean?
Then, it mentions “global maps”. The plural indicates that there are multiple. And what does “global” mean? “global”, typically is in the context of where something can be seen, and it means it can be seen anywhere. In a source code or running program, it means inside any function, block, class, etc. But the namespace context clearly is something different, because it's about compiler. So, what does “global” mean in a compiler context? And, is it appropriate to dip into compiler context when explaining something about the language? Can we explain Clojure “namespace” and or “intern” without mentioning “global map”? By “map”, does it mean clojure's map datatype? If so, then does it imply that the “namespace system” is implemented using Clojure?
Then, the sentences goes on “… to Var objects”, and essentially says the namespace system has a map, that a new var object is either in it or not. It basically gets very complex if you are trying to turn this sentence into symbolic logic. If you are a good logician, but unable to do so, that means the writing failed to be clear.
of course, when vast majority of programers, one basically understood that it just some name lookup table. All the detail is hand-waved. If they need to know more, they look at the source code to see how exactly its done. This is when, technical writing failed. Best example is unix and its man pages.