Why isn't clojuredocs a mess?

documentation

#1

Clojuredocs.org has been a wonderful resource for many years. This is kind of puzzling, because anyone who registers as a Clojure contributor can add arbitrary examples, comments, and links to other functions to a function’s doc page.

I once suggested creating something similar in another language community, and the response was, “Oh, no. A doc site has to be carefully managed and curated by a small number of people, or it will be overrun by foolish newbies and web-spammers, and become useless.” That seems entirely reasonable. (There is now have a nice site in development over there, but it is much more carefully controlled than clojuredocs seems to be.)

So why isn’t clojuredocs a mess? There are occasionally examples or comments that don’t exactly need to be there, but for the most part, everything I see there is potentially useful.

What explains this?

Do the creator, Zachary Kim, and others spend a lot of time weeding out junk? There’s no indication that I have found on the website or the github repo pages that this is part of the process.

Are Clojure developers, including newbies, all just reasonable people? (Would this change if Clojure were as popular as Python or Java?)

I’m curious about this, but it’s a valuable question to answer because it’s a potential lesson for other doc sites for other technologies.

(I’ll write to Z. Kim as well but I thought it would be worth discussing publicly here.)


#2

I think there are not a lot of people willing to edit those pages. In some cases, this might be because folks new to Clojure do not feel confident enough that their changes would be correct or useful.


#3

I love Clojuredocs. I wish Cider used it instead of Grimoire, as it has more and better examples in my opinion.

I think if bad examples or bad notes ever became an issue, adding a up/down voting system to them would solve the problem.

And if bots and spam became an issue, recaptcha could be used.


#4

Because Clojurists are a wonderful and amazing group of people, obviously.


#5

So Clojurists have good judgement as well as being amazing and wonderful.


#6

It would be better if it released a CHM offline file each year (or season), which could be easily used locally.


#7

Thank you Zachary for a wonderful resource (in case you’re reading this)