My hope is that we can do some really good things to help two of the biggest complaints here: Tooling and Documentation.
On the tooling side, the next version of the Light Table Playground will be even more friendly than the previous one and seeks to make it a one click experience to go from nothing to a complete Clojure env. It's also getting tutorial content and a few other things that should make it far easier for people just starting out.
In terms of the documentation and discovery problem, I think we just need to push documentation into the community's culture and I imagine the best way to do that would be to make tools that make beautiful documentation easy. We have codox for the generation of API docs, but nothing for longer form documentation and I haven't seen an environment that really embraces both the consumption and creation of docs - this is a problem I really want to see tackled in Light Table and I think there are some very cool potential solutions.
> the best way to do that would be to make tools that make beautiful documentation easy.
Really? I find it hard to believe that the problem is caused by a lack of tools. Clojure already has five or six tools for spitting out a programmatically-generated HTML overview of the shape a given project.
Instead I think it's clear the reason this doesn't happen is that good documentation is really difficult to write and people don't want to put the necessary effort into it. Putting aside the obvious problem that good English prose is really difficult to write, you have to overcome the fact that the people qualified to write the documentation don't much benefit from it. On top of that, it's very difficult for an experienced user to put himself in the mindset of a beginner.
In fact, I'd go so far as to say that the existence of all this existing documentation tooling only goes to reinforce the harmful notion you can just run something like marginalia over your codebase and publish the HTML output somewhere and consider your project documented. Sure, API overviews are valuable as a reference, but they're mostly just a distraction to someone starting out who just wants to figure out whether the project is a good fit for their needs. Long-form prose documentation is crucial at that stage, and it's awfully hard to come by.
Anyway the tooling is trivial--getting an overview of the API and docstrings has been done over and over, and rendering a pile of prose in markdown files is hardly rocket science. The real problem is cultural.
We don't actually disagree - I said just before that that we need to push it into the culture :) The way to do that is to make beautiful docs the norm, which is what I tried to add to Noir and Korma. And you're right, it is really hard, but we need to at least convince people to try. While not solved purely at a tooling level, I think tooling can go a long way here by creating interesting and obvious ways to document things in a more meaningful manner than simple API docs. If the cannonical tools for the language are all encouraging you to write long form docs, I have a hard time believing that everyone will simply ignore that.
In the end, however, it comes down to us; the people using the language and writing the libraries now to do exactly this. It's why I spent so long writing stuff for Noir and it's something we as a community that already exists need to do better.
Maybe. I'll withhold my judgment till I actually see such a tool, but I suspect tooling and design function more as distractions when it comes to documentation; in my eyes the only thing that matters is content.
As for pushing documentation into the clojure culture, having on-demand online docs for any clojar or github repository would go a long way. We don't even have to reinvent the wheel as it's already been done in ruby, http://rubydoc.info/ (source - https://github.com/lsegal/rubydoc.info).
Marginalia was never intended as a system for writing longer form docs... but truth be told I don't know what "longer form doc" means. User manuals?
In any case, Marginalia is trying to fill the "code-reading" space rather than the API and user-manual nitches. For the latter case, I've been experimenting with another tool.[1]
By linking to rubydoc.info, I was referring to online docs that index functions/namespaces/classes/files and make them searchable which is different than reading formatted markdown.
On second thought, I'm not sure if any of this would go a long way as I don't know clojure's culture too well yet. I just know I've found indexed docs to be valuable in ruby when linking to and discussing a library's API.
Yeah, the main difference is that Clojure docstrings are available at runtime, so it's easiest just to query a running instance; you don't need to switch to a browser to do that kind of thing.
There's a place for API reference pages, but considering that most tools to generate it require evaling the code in question, a third-party hosting service would have to implement some fancy sandboxing and wouldn't really offer much over GitHub Pages since it's just static HTML.
But I don't think when people complain about documentation that they're complaining about API reference. I suspect people want accessible tutorial-style prose and introductions. But maybe next year's survey could distinguish between the two.
I'm happy to hear that. I already made light table my main IDE for tinkering and solving 4clojure assignments. For the most part I've dumped emacs/SLIME for everything but lazy seq stuff which is problematic to run in light table - and for saving and managing project files.
Good documentation with examples, especially integrated R/W documentation is absolutely essential. Integrated clojuredocs etc.
I don't think PHP would be still around if the docs were more like docs in other langs. People can give additional examples there, describe bugs, differences in various versions, even small programs demonstrating the intended use or a workaround. It could be a lot better technically but it's very clear that it is super useful and a great time saver.
> I think we just need to push documentation into the community's culture
Yes.
> and I imagine the best way to do that would be to make tools that make beautiful documentation easy.
Well, we've already got "built-in" tools that make handsome docs (maybe not beautiful, but certainly nice enough :) ). That is to say, almost all Clojure projects are on github and github automatically renders .md files into lovely html. With syntax highlighting too, if you label your blocks like so:
```clojure
(some :clojure "code")
```
So, just encouraging authors to add a some doc/*.md files to their project would be an excellent start. :)
On the tooling side, the next version of the Light Table Playground will be even more friendly than the previous one and seeks to make it a one click experience to go from nothing to a complete Clojure env. It's also getting tutorial content and a few other things that should make it far easier for people just starting out.
In terms of the documentation and discovery problem, I think we just need to push documentation into the community's culture and I imagine the best way to do that would be to make tools that make beautiful documentation easy. We have codox for the generation of API docs, but nothing for longer form documentation and I haven't seen an environment that really embraces both the consumption and creation of docs - this is a problem I really want to see tackled in Light Table and I think there are some very cool potential solutions.