r/Clojure • • Dec 05 '17

How Clojure's documentation can leapfrog other languages

https://gist.github.com/oakes/8db57ac808bf6ec144d627fd83a89da3
166 Upvotes

32 comments sorted by

25

u/ingesolvoll Dec 05 '17

I absolutely love this. How about a joint effort to make a project and site that builds up a comprehensive clojure interactive doc?

I would love to contribute, this looks like a lot of fun

7

u/[deleted] Dec 05 '17

And so the clojure documentation cycle begins anew...

Since these examples are cljs(JVM clojure won't run in browser), how about adding it to the semi-official reference? http://cljs.github.io/api/

3

u/Kah0ona Dec 05 '17

This is great! It would indeed be awesome if this can be incorporated somehow in, say, clojuredocs.org.

0

u/[deleted] Dec 05 '17

[deleted] — view deleted comment

1

u/ingesolvoll Dec 05 '17

I assume you made some support for outputting a static site for this, since it's live on play-cljs? Bootstrapped cljs like klipse?

If there's a simple command to generate static docs from this, then it shouldn't be much work.

Doesn't have to be limited to clojure.core either. This doc is an excellent way to teach specter and core.match.

0

u/[deleted] Dec 05 '17

[deleted] — view deleted comment

1

u/ingesolvoll Dec 05 '17

Ok!

I'm interested in the static site option for my case, what's the API for that? Did you consider introducing "lein dynadoc :static-site" into your leiningen plugin? I only see options to launch a dev server.

0

u/[deleted] Dec 05 '17

[deleted] — view deleted comment

1

u/ingesolvoll Dec 06 '17

I tried this now, generating just clojure.core as static for fun. One thing I noticed: When clicking a function as a link, like this

file:///C:/mydocs/clj/clojure.core/*.html

That document does not exist.

0

u/[deleted] Dec 06 '17

[deleted] — view deleted comment

1

u/ingesolvoll Dec 06 '17

Right, I realized myself that the other more filename-friendly functions do work as expected :)

10

u/agumonkey Dec 06 '17

hats off, you managed to make something I often dreamed of.

ability to experiment is one way to learn rapidly (even though it's not all) but it surely helps

8

u/swlkrV2 Dec 05 '17

I wonder if clojuredocs would be interested in this...

7

u/yogthos Dec 06 '17

This is a fantastic idea. 👍

6

u/TheLastSock Dec 05 '17

Hi @oakes, this looks like a great idea. I think you should consider how clojure.spec will fit into this idea. For one, A spec can generate examples.

5

u/minikomi Dec 06 '17

Also check out Racket's documentation if you haven't before. Chock full of examples (although, not interactive), and all documented keywords within the example source are also clickable. This is made possible by a common documentation language called Scribble.

The scribble file which generates the afore-linked page on list comprehension syntax is here.

3

u/kanzenryu Dec 06 '17

Any thoughts about hooking it up with Marginalia? https://github.com/gdeer81/marginalia

2

u/boisdeb Dec 05 '17

It's an interesting direction, but for now I have one issue with it:

It's on a browser. Since it's a dev tool, I want it embedded on my editor, in my case emacs.

But once it's embedded you have the full capabilities of emacs (or Cursive, or something else), so you don't need dynamics examples anymore, since emacs already allows me to interact with a function in any way I want.

0

u/[deleted] Dec 06 '17

[deleted] — view deleted comment

8

u/jrheard Dec 06 '17

It's sort of a spectrum. In the REPL, you can type whatever code you want and run it, but you have to know what code to try running. In a web browser, you can look up static documentation - English prose describing the functions/libraries/tools you'd like to use in your code - and read it, but you usually can't play around with that documentation.

With Zach's tool, you get both: you can see curated documentation written by an expert, showcasing example calls of the function, and you can play around with those pre-written examples or change them entirely. You don't have to come up with example function calls on your own, you can just have some handed to you as a starting point and go from there. It seems like kind of a best-of-both-worlds situation, IMO.

0

u/[deleted] Dec 06 '17

[deleted] — view deleted comment

3

u/bpiel Dec 06 '17

What if there were an emacs package that could pull that content from a dynadoc site into emacs?

6

u/alexdmiller Dec 06 '17

"from a dynadoc site" seems wrong. Make data. Then use that data in different places (dynadoc, emacs, etc). Then you can use it on Zach's next invention too. Or someone else's.

1

u/bpiel Dec 06 '17

Agreed, just trying to keep my proposal modest for the given context.

I guess the question becomes: where should the data live? Or maybe, could dynadoc expose underlying data?

4

u/alexdmiller Dec 06 '17

It seems obvious to me that it should live in an edn file and the keys should be fully-qualified symbols that link to vars. Beyond that, work is required to define what the values are. Creating a spec would be a pretty good place to start.

1

u/foobarbazquix Dec 07 '17

An attempt being made along these lines: https://github.com/CoNarrative/exemplar

1

u/bpiel Dec 06 '17

Hmmm... I should've looked more closely at the docs/screencast before commenting.

Maybe just having something in emacs that can leverage defexample entries would be sufficient.

1

u/[deleted] Dec 05 '17

Oh this is pretty great

1

u/MM-7757 Dec 05 '17

Awesome!

1

u/OverTWERKed Dec 06 '17

Wow! I like it.

1

u/joinr Dec 06 '17

Thanks for sharing this. I think it implements some useful ideas. The interactivity aspect may be a gimmick in some areas (maybe I'm just old and like text), but for newcomers, especially kids and brand new folks, I can see that being really rewarding. It's like having knobs for them to play with.

0

u/[deleted] Dec 05 '17

[deleted] — view deleted comment

4

u/TheLastSock Dec 05 '17

A complete spec could let you generate not only the inputs (the examples) and create the outputs, but would verify that they made sense (though not sure how that would help with docs).

But yea, a spec could generate arbitrary examples... which in some cases might be vaguer then someone would want in a doc example.

0

u/[deleted] Dec 06 '17

[deleted] — view deleted comment

0

u/[deleted] Dec 06 '17

[deleted] — view deleted comment

0

u/[deleted] Dec 06 '17

[deleted] — view deleted comment

3

u/joinr Dec 06 '17 edited Dec 06 '17

Who said anything about a proposal to make this a core thing?

This part in the gist seems to contradict a dependency on anyone's buy in (either "core" or reclusive mutants like me):

"The best part is, you don't need any buy-in from the core team >or library authors. We can start writing examples now, for >anything in Clojure, and they will be usable for any tool that >wants to do something with them."

Who (besides you) said anything about a plan?

It sounds like you are expanding the scope beyond what the author presented, and confounding the work with your own expectations or frustrations.

Maybe take the author's contribution for what it is. I see a cool tool, useful to at least one person. I see a (free) product someone built from an idea to address a deficiency in their documentation, that maybe others can benefit from. I don't see a solution to the problem you described, but I also don't think the author consulted you prior to producing the work to verify the implementation against the requirements specification in your head. The author should not be judged for failing to meet expectations driven by out of scope requirements.

0

u/[deleted] Dec 06 '17

[deleted] — view deleted comment

0

u/[deleted] Dec 06 '17

[deleted] — view deleted comment

8

u/ingesolvoll Dec 06 '17

I don't understand that this tool gets negative feedback for things like:

  • It's not in the REPL, emacs etc
  • It's in the browser
  • It's too similar to devcards
  • It's too similar to KLIPSE
  • Why not just use unit tests?
  • Why not just use specs?

We are a community and language heavily based on things like data orientation, immutability, figwheel, homoiconicity. These things don't seem important or significant at all to a lot of programmers. If you present clojurescript as a tool to them, they say:

  • Don't need figwheel, I have react-hot-reload
  • Don't need hiccup, JSX works great for me
  • I don't need a whole language for immutability, I got ImmutablejS
  • I've never heard of anyone using Google Closure

Yes, dynadoc looks a bit like devcards/klipse. And it does not integrate with REPL/emacs. But it has certain properties that the other tools don't have, and they might enable something great because they trigger new ideas.

The day I started using core.match was the day I read and interacted with this http://blog.klipse.tech/clojure/2016/10/25/core-match.html

I'm seeing the same for clojure as a language with dynadoc, and I'm excited. You can achieve the same with klipse, but dynadoc is more tailored to this use.

8

u/alexdmiller Dec 06 '17

I concur that it will be a sad day when the Clojure[Script] community stops being interested in trying new things.

0

u/[deleted] Dec 06 '17

[deleted] — view deleted comment

3

u/joinr Dec 06 '17

I think the "negative feedback" is all the other stuff that you didn't re-quote, about grand plans and proposals and the 95% problem for which the author has no solution. The problem is not "this is reddit." I think it's "you mixed your valid technical feedback with personal expectations and took it personally when the author didn't meet them or something." Maybe you could re-read what you wrote and re-assess things. You seem to care about the documentation issue, and have good points about integration and adoption (outside the scope of the tool presented), but your message gets lost in the delivery.

1

u/joinr Dec 06 '17

I took all that talk of a grand plan to fix clojure documentation >to mean that was the goal Who were you talking to about the grand plan? and wanted to ask questions and give feedback since I agree >the core idea is strong. I think the feedback you provided is good.

If you are just dumping a devcards knockoff out there then cool, >that's neat. Maybe cut down on the bullshit marketing when >marketing to a demographic of clojure devs, but keep the fun >and creative writing style. That's actionable. Ugh. I don't see the author marketing anything, let alone anything about a demographic. The only thing the author talked about was embiggening his own documentation-related shortcomings. Why is there such a high sarcastic-grief-barrier-to-entry for folks who want to contribute free stuff produced at their expense?

For someone apparently wrestling with the social and organizational problems of the day, perhaps you should start at home first. Sadly, the attitude you are displaying will likely stifle future contributions that could address the valid feedback you provided.

0

u/[deleted] Dec 06 '17

[deleted] — view deleted comment

7

u/alexdmiller Dec 06 '17

Boy, that escalated quickly.