hexdocs.org is awesome! I hadn’t seen that before. I’d definitely like to see the state of Clojure’s documentation overall improve, and I agree that having better tools for writing and sharing documentation is a important to that effort. Having a single, central domain such as say http://docs.clojars.org which leverages the existing clojars property would also dramatically help discoverability and searchability via Google of hosted documentation. Spreading docs out over lots of github pages and wikis defeats a lot of the heuristics Google uses to determine page rank and leads to the repositories themselves frequently being higher link score than the doc pages.
One idea worth exploring is Maven’s existing support for classifiers. Particularly, the Java ecosystem already uses the “javadoc” classifier to deploy documentation alongside jar artifacts.
As @plexus already noted, it’d be pretty trivial to steal compute resources from clojars if there’s an execution model – java bitcoin miner and all that. Coming up with a standard for how documentation is built and distributed as a static file format solves that entire problem.
There’s already some work in this area. For Grimoire, I developed a Maven-inspired store structure for documentation, notes and examples – lib-grimoire. Later, a GSoC student I was mentoring came up with a related specification – lib-grenada.
Building a plugin to make deploy generate and push a documentation jar as shouldn’t be too hard. It also gives people a natural offline documentation story, because docs are just a jar that Maven can fetch and cache.
To take a step back here, I’d like to point out that there’s a lot more to documentation than just API documentation.
I wrote conj.io working from the assumption that all you really needed was API documentation – If you just generated API docs users would be able to discover what they wanted (or needed) and life would be good. This turned out to be very false. Grimoire’s primary value add was its cheatsheet which related symbols to each-other along logical lines. I did disfiguring damage to the site and my traffic metrics reflected it when I started making changes to the cheatsheet without appreciating this fact.
While Codox supports articles, all the uses I’ve seen treat it like Javadoc which makes this same assumption that gendocs are sufficient.
This and other experiences leads me to think that documentation needs to encompass examples, cookbooks, API documentation and full length articles all of which need to be able to reference each-other. API docs are good, but unless you can relate the API to concepts it’s difficult to navigate them. Motivational and architecture documents are far more valuable when related to examples which are themselves far better when indexed against the API.
Doing what Grimoire does and maintaining a glorified tree of maps from fully qualified names to markdown files is nowhere near sufficient. It may be adequate for the backend, but it’s not the view you want to show users. Stacks is my attempt to sketch out some forms of more general documentation as data, but it’s nowhere near ready for use.
I suggest that stealing from Grimoire/Grenada, designing a spec for some documentation index datastructure and MVPing something that builds and renders it is probably the right way to move this forwards. At least that’s what I’m trying to do with stacks.