Reading clojure docs is a PITA | Hacker News Reader

Reading clojure docs is a PITA

medium.com

1 pointtotemizer11 comments

One constant is that people are always complaining about the docs. One Ruby on rails guy told me it is open source and you can fix what frustrates you.

I could also just make my own hardware and write my own software from scratch. Even better, I could invent new math, new formalism, theoretically I could do all those things.

But you know, I think it's a fucking stupid idea to ask noobs to fix the docs. Not sure who was the first idiot who came up with this, but it completely explains the state of the clojure docs, if it's the beginners who you task with writing it.

Clojure only exists because lots of people have worked on it.

I went to a small hackathon that brought together a diverse cast of engineering students and software professionals and my team did not have an ambitious idea, so we fixed something unclear in the Ruby-on-Rails docs about what a standard library function does.

I hardly ever program in Ruby, but I contributed by looking at the C source code for that function and based on what I knew about C, confirmed they were right, so we added a few sentences and made a pull request then walked home with GitHub branded water bottles.

The core developers of Clojure are very busy and and they know the software very well so they are incapable of understanding what it is like for a noob -- a beginner has the unique viewpoint of what it feels like for a beginner.

A commercial software company has salespeople, sales engineers, product managers, project managers, designers as well as wildcat coders who try to simulate the "voice of the consumer" but in the case of open source you pay no money but you have to speak for yourself.

We've got free speech and you've got the right to complain. But really, if you are learning a subject like Physics you will go to a lecture or read and take notes as a basic part of understanding the material, programming is no different than that.

In the big picture it isn't much of a stretch to write your notes into the official documentation since the next time you need to look something up you'll see something great.

It is not at all like "making your own hardware" because this is a matter of making a the smallest possible change in something that already exists and typically has a good build system, version control, and tools in place to make the change.

Beginners didn't write the Clojure docs. The clojuredocs website are not the Clojure docs (just like it says on the clojuredocs homepage).

Noting that the site being complained about is not the Clojure docs site.

https://clojuredocs.org is not clojure docs? What it is then? Rust docs? Clojure templates? C++ docs? Clojurescript framework? Should be moved to howtofuckwithpeople.org

Ah, pedantry and sarcasm--hilarious! I love this game. I'm good at it.

No, clojuredocs is not the Clojure docs. It's a Clojure docs. As the OP noted, the actual Clojure docs are well-formatted, and significantly more complete.

(In fairness, I do envy the free time you have to complain about someone else's efforts. I don't often have the time to focus on irrelevancies. I've appreciated the break. Thanks!)

That's how I feel about reading clojure code.

What's your preferred language?

Scala. But to be fair I think reading Scala docs is a PITA too.

That brings a smile to my face :) I feel similarly reading Scala code :D I know it shouldn't be so surprising, but it still amazes me how people have different preferences on syntax.

Reply on news.ycombinator.com