
Reading clojure docs is a PITA - totemizer
https://medium.com/@johnsontabouret/reading-clojure-docs-is-a-pita-a1097cab08fb
======
PaulHoule
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.

~~~
totemizer
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.

~~~
PaulHoule
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.

------
eip
That's how I feel about reading clojure code.

~~~
grzm
What's your preferred language?

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

~~~
grzm
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.

