Clojurians Log v2

So there’s been a lot of talk lately about the lacking Clojure documentation. I’ve never had a problem with it but I’m more than happy to work on it for others. My question is, what exactly is missing? I have a bunch of my personal notes that I’m working on making more presentable for the Clojure site, but if there’s something in particular that’s missing, I’d rather redirect my effort.

That's a really good question. I've noticed that the maintainers of Clojure aren't big fans of having roadmaps which give guidance or direction.

My feeling is there is a gap on http://clojure.org and http://clojuredocs.org around api references. apidocs are a poor subsitute for more contextualised information.

I think Django is a good role model for documentation efforts. Here's what they have: https://docs.djangoproject.com/en/1.11/ref/ and here's one of their leaders talking about good documentation: https://jacobian.org/writing/what-to-write/

The section titled "Reference" resonates for me

"Think of guides and reference as partners: guides give you the “why,” and reference gives you the “how.” Following the deque example, some sort of “guide to data structures in Python” could give an overview of all the different types of data structures in Python (be they built-in or standard library), linking off to the documentation for each module and type for the complete details. It’s really tempting to use an auto-documentation tool like Javadoc or RDoc for reference material. Don’t. Auto-generated documentation is almost worthless. At best it’s a slightly improved version of simply browsing through the source, but most of the time it’s easier just to read the source than to navigate the bullshit that these autodoc tools produce. About the only thing auto-generated documentation is good for is filling printed pages when contracts dictate delivery of a certain number of pages of documentation. I feel a particularly deep form of rage every time I click on a “documentation” link and see auto-generated documentation. There’s no substitute for documentation written, organized, and edited by hand. I’ll even go further and say that auto-generated documentation is worse than useless: it lets maintainers fool themselves into thinking they have documentation, thus putting off actually writing good reference by hand. If you don’t have documentation just admit to it. Maybe a volunteer will offer to write some! But don’t lie and give me that auto-documentation crap."

That was a really great write up @olivergeorge! I’m going to spend some time looking at the Django documentation and building a ‘roadmap’ for Clojure. Having a roadmap that the content creators for the Clojure site decide is good, I think, will be a great way to give the documentation effort some structure and direction.