To who exactly the references made in clojure.org is written for?

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

5 Likes

I’m inclined to agree with you. I raised it with @alexmiller and he asked me to create a placeholder issue in GitHub for it: https://github.com/clojure/clojure-site/issues/419

5 Likes

I was a CommonJS programmer and it took me several weeks(or months if counting from the time I read about it) to understand how namespace works with classpaths for Clojure(Script) packages. People seem to have zero difficulty understanding it with Java background. Really atrocious.

3 Likes

I love the Clojure official reference. I read it from start to finish and in a very short time I knew almost everything about Clojure.

I also understand that it is incredibly dense and precise, which is why I like it. Going through Brave and True takes a lot of time, the reference gives you much more info much more quickly. It reminds me of the Java reference in that way. Now, I wouldn’t mind it being expanded, but please don’t take details and specific things away, that’s the best part of the reference, some of that information cannot be found anywhere else.

That said, the need for something a bit more superficial and less dense makes sense. But I think that could be separate. Something like https://elixirschool.com/en/ but for Clojure would be nice. Brave and True gets pretty close, but it doesn’t get updated. It could be nice to see a kind of Clojure School section on the official website which mimics that style.

5 Likes

I think you’re damm right, me myself already used clojure.org reference in the past when looking for detailed answers. Maybe they could separate this in an advanced section, or as you said, enforce newcomers to go to somewhere else like this Elixir school, i think there is room for everything when we are talking about learning resources, that’s why asked in the title, to who exactly this is for? I’m not saying it’s wrong, I’m saying it’s for experienced people who already know something about clojure, so maybe it’s not in the appropriate place, but it’s valid and good content, but we have to make sure we are creating a comfortable place for newcomers, and I strongly believe that the official website should create this feeling.

1 Like

I tend to agree, a way to fix the perceived problem is to place links that can guide the reader to obtain more information as needed.

2 Likes

but we have to make sure we are creating a comfortable place for newcomers, and I strongly believe that the official website should create this feeling.

This topic of (official) clojure not being good (easy enough) to beginners/newcomers seems to pop up every couple of months. We were all newcomers once and we managed to get by with what few docs were available at the time in as uncomfortable places as we could possibly find them.

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

The one that’s really trying to learn will find a search result they can understand or they’ll ask somewhere. You’ve looked further and you’ve found better explanation for your readers.

I’m probably missing something but I don’t understand what does helping a newcomer on an official site accomplish that helping a newcomer on an unofficial site doesn’t. Why should official website be a comfortable place for newcomers? Is this https://clojure.org/guides/getting_started not good enough?

1 Like

I think you have a good point here. My main concern really, is about not scaring people away just because it seems “hard”, and if we face reality, lot’s of people will be scared about that.

I love Clojure and i think a lot of people would love seeing the community getting bigger (although being small has it’s advantages off course).

I was having this discussion on the clojure group for brazilians at Telegram, and we got to the conclusion that the official website could link to another explanations, or instead, clojure could have something like: https://elixirschool.com/
Perhaps i’ll create another topic later to discuss the possibility of having a “clojureschool”

1 Like

Yes but we supposedly also want the not already sold ones, not just the ones who already want to learn Clojure thoroughly.

There are lots of people who are just curious about e.g. functional programming and want to check out what’s all the fuss about and more accessible official pages would help Clojure’s appeal a lot.

2 Likes

It probably would be also helpful to add links to documentation/guides about differences between Clojure and Clojurescript in regards to namespaces, for example: namespaces are not first class citizens in Clojurescript, i.e.: there’s no *ns* and you can’t do (ns-name *ns*).

Upd: I just have discovered a little hack. In Clojurescript you can do: (symbol (namespace ::_)) for the same effect as (ns-name *ns*) in Clojure.
Furthermore:
in Clojure: (ns-interns *ns*),
in Clojurescript: (ns-interns* (symbol (namespace ::_))) ; note the asterisk

This is a classic case of ”That which is seen, and that which is not seen”. As I understand it, the OP is concerned with the latter, worrying that Clojure loses (an unknown number of) people, that could have been made more comfortable and possibly stayed and listened a bit longer, if the first place they look for information also had them in mind. It’s possible that this is a valid concern, right?

3 Likes

or: survivorship bias :+1:

1 Like

Although there’s definitely room for improvement in that text, I think part of the disconnect here is that a reference is a very different thing from an introduction. It would be nice if the documentation were split between something quite terse and specific with a couple of examples for each case to be used by experienced people (see the Common Lisp HyperSpec for an example of this done pretty well) and another resource designed for newcomers. Generally, I send people to Brave and True for the latter, but it would be nice to have something official that was equally gentle.

I’ll reply to all of you @matthewlisp, @mario and @PEZ, because it seems like you’re saying the same thing.

If I understood you correctly, you believe that due to the lack of appropriate docs, significant amount of newcomers is lost prematurely and permanently. Is this a gut level feel or do you have any examples to support it? Would you say that the rate of experiencing problems related to bad documentation is higher than in other languages? Could it be the case that it just seems higher because of the solution being terser?

There are two groups of newcomers - those with prior programming knowledge (P) and those without (N). The N group is not helped by clojure.org and it’s also not helped by official website of any other programming language (except python). I believe the P group is adequately served by https://clojure.org/guides/getting_started, https://clojure.org/guides/learn/syntax and https://clojure.org/community/resources. What does elixirschool.com have that clojure.org doesn’t?

For the record. I do not think Clojure suffers from bad documentation. I am a big fan of the precise, boiled-down-to-the-very-essence style of documentation. It reminds me of the joy I felt learning about tools like awk and sed from the System V manuals. :smile:

But, yes, I have a feeling that there could be room for improvement in terms of stickiness and more growth of the community, when it comes to how the ”official” site presents information. This without having data to prove it, or even a concrete suggestion on how to improve it. I just think it is a very valid concern, and that Clojure is important enough to warrant turning every stone in search for more users. And at the very least, I think that the existence of people who have stayed, is poor proof of how perfect things are. People are very different.

There is actually a big gap in the docs you linked on clojure.org. There’s pretty much nothing introducing namespaces and showing how the convention with source files works, or how to organize code into files/namespaces.

My first reaction to Matthew’s original post was “Oh, c’mon, there’s got to be beginner material on clojure.org about namespaces!” but then I went and looked. Nothing in Getting Started or the “learn” section gets into files or projects or how to use ns. It all deals with the REPL.

That’s covered in Brave & True and all the books of course, plus several random tutorials out there. But it really should be on clojure.org as well.

2 Likes

I agree that a lot of the complaints about documentation are essentially a lack of agreement on the “desired audience” and consequently no clear exemplar that should be aimed for.

On the audience front - @doubleelbow and @PEZ reflect the current audience and style of the documentation that is “boiled-down-to-the-very-essense” style of documentation. I would characterise this as a sort of ‘mathematically formal’ approach.

I don’t have a formal background, and am not particularly mathematical, I learn best by practical example and extended explanation. So for me the current official documentation is opaque, it’s not ‘boiled down’ so much as inscrutable.

Here’s a practical example of how the two approaches:

The Python one gives me some context to what the type is and examples of how to use it. I specifically chose a core language element rather than a function.

The documentation for functions between the two languages makes the difference in approach even more clear:

Given the current make-up of the community it’s likely to be hard to change the approach, but perhaps agreeing an exemplar so there’s something to aim for would help.

Dan Abramov (of the React team) has a habit to adding a banner to his more deep down and esoteric posts, stating that: “This topic is not required knowledge to use React, so don’t feel bad if you can’t digest it all”.

Perhaps the reference in Clojure.org could have something similar, perhaps pointing to the guide or some other resource.

1 Like

That’s not the right link for Clojure Map datastructures, you want: https://clojure.org/reference/data_structures

The one you linked describe the reader syntax for Maps.

Or, if you want the beginner-friendly version of (sets and) maps: https://clojure.org/guides/learn/hashed_colls