Clojurians Log v2

I normally hate open source documentation, it's normally poorly written and incomplete, re-frame documentation is brilliant. If everything I had to use day to day had as well thought out docs as this my life would be so much easier and happier. Trying to learn it and going from THE BASICS and working through the docs is a joy. I like this 60,000ft > 30,000ft > 0ft approach it takes.

Yeah, when I looked at re-frame recently, I was very impressed by the docs.

How many times did you improve the docs, once you knew what was missing?

Not everyone will agree, but external docs seem to me a pretty flawed idea to begin with. Clojure was designed for us to create introspectable systems (evidence of this being the reified namespace/var objects, the metadata system, the repl, etc). So learning about a project for me means either git-cloning it and running it, or depending on it and introspect it with my repl/ide It needs some discipline, and perhaps some initial work for making tooling always work, but it pays off :)

Depends a lot on the type of library/framework. It’s also hard to write a good introduction ment for people unfamiliar with the whole project, if you build it from scratch.

One could argue that the 60,000ft thing isn't even 'docs' - that's more of an architectural overview 99% of clojure libs don't need one, they're just a bag of defns :) They do generally have an intro, rationale, etc expressed in .md form, that seems nice and complementary to .clj introspection