3 ms·

Isn't marginalia, https://github.com/fogus/marginalia https://github.com/fogus/marginalia, one attempt at longer form docs? As for pushing documentation into t

Isn't marginalia, https://github.com/fogus/marginalia https://github.com/fogus/marginalia, one attempt at longer form docs? 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/ http://rubydoc.info/ (source - https://github.com/lsegal/rubydoc.info https://github.com/lsegal/rubydoc.info).

fogus 14y ago
> Isn't marginalia 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] [1]: http://www.github.com/fogus/trout http://www.github.com/fogus/trout
technomancy 14y ago
> having on-demand online docs for any clojar or github repository would go a long way. How so? Isn't GitHub already its own on-demand online docs service? https://github.com/technomancy/leiningen/tree/master/doc https://github.com/technomancy/leiningen/tree/master/doc https://github.com/technomancy/clojure-mode/blob/master/doc/index.md https://github.com/technomancy/clojure-mode/blob/master/doc/...
- cldwalker 14y ago
  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.
  - technomancy 14y ago
    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.

fogus 14y ago

> Isn't marginalia 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] [1]: http://www.github.com/fogus/trout http://www.github.com/fogus/trout

technomancy 14y ago

> having on-demand online docs for any clojar or github repository would go a long way. How so? Isn't GitHub already its own on-demand online docs service? https://github.com/technomancy/leiningen/tree/master/doc https://github.com/technomancy/leiningen/tree/master/doc https://github.com/technomancy/clojure-mode/blob/master/doc/index.md https://github.com/technomancy/clojure-mode/blob/master/doc/...

cldwalker 14y ago
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.
- technomancy 14y ago
  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.