Fork me on GitHub
#cljs-experience2017-05-25
>
Yehonathan Sharvit09:05:52

I’m curious to hear what you guys think about the value vs. the price that Klipse brings to a tutorial/doc website

Yehonathan Sharvit09:05:03

value: code interactivity

Yehonathan Sharvit09:05:56

price: high payload - klipse_plugin.js is 7MB 780KB gzipped around 1 sec to download

martinklepsch09:05:47

@viebel consider that this 1s might not be the same for everyone and that some may have smaller machines that don’t do too well with large amounts of JS

Yehonathan Sharvit09:05:00

@martinklepsch We are targeting developers aren’t we?

Yehonathan Sharvit09:05:09

They should have strong machines 🙂

daveliepmann09:05:38

I'll comment because I was in the original twitter thread, but since I may be a wet blanket I will keep my commentary to a minimum unless asked. If the goal is to make it easier for Clojure(Script) noobs to get started, I think the first question for every idea should be "what solutions have been tried?" and the second question needs to be "what resources already exist, and how are they doing?" I think the proposed ideas in this channel could be great, and I don't want to discourage anyone from making something new and awesome. But please consider existing solutions, especially official ones that are open to contributions! http://clojure.org and http://clojurescript.org will (and should) be the default first stop for newcomers, so optimizing that experience should be a higher priority than creating an alternate resource--and they're open to issues and PRs on github. http://clojure-doc.org exists and already has the categories proposed above. For function documentation (separate from getting-started docs), http://clojuredocs.org and http://conj.io exist. The places where I see a lot of potential for improving the newcomer experience is fleshing out https://clojure.org/guides/getting_started (perhaps turning that page into the tl;dr and writing a more detailed step-by-step walkthrough to get from nothing to running a simple app), adding context and explanation to https://clojure.org/community/resources, and creating step-by-step, hold-your-hand, well-tested instructions for individual editors (emacs/cider, vim, atom, etc.). I think code playgrounds and tutorials are an entirely separate problem from "getting started" and function documentation, and all three are big, difficult problems to solve, so maybe don't try to solve all three in one project.

genRaiy09:05:22

how do we know if something works? visitor numbers and engagement would be useful to see in the open

genRaiy09:05:56

basic things like …. if version A with Klipse is more engaging than version B without it, drop version B and move on. Without some feedback loop this is all projection

genRaiy09:05:23

and I think conference talks as a feedback loop isn’t working out too well for us 😉

genRaiy10:05:27

(how to achieve this will obviously depend on platform / hosting choice)

mekza10:05:59

@daveliepmann http://clojure-doc.org is very good, imho problem here is new comers don’t want to spend hours reading stuff, that’s a bit “old way to learn”. I come from Python world where we had this problem prior Python 2.5. Since there is a bunch of initiative to help newcomers and it’s not even on PSF website, PSF has a repo with all the guides you can find etc. https://wiki.python.org/moin/BeginnersGuide/NonProgrammers

Roman Liutikov10:05:36

Hello! I think we could learn from Reason/OCaml story, it’s amazing how fast it grows, though their Discord channel is still pretty small.

Roman Liutikov10:05:21

I’ve been talking to Cheng Lou recently, the guy behind ReasonML, about the way they evolve the community around the language. It seems like they are pushing hard social aspect while also providing essential tooling which is easy to start with. They integrate very good with NPM/Yarn. In fact he said, and I agree with him, that in order to get more people on board we should be closer to what they are used to, things should be familiar. The problem is that most devs want a single-click solution which I guess is not something we would want to provide. Quick on board experience is as important as returning experience.

Roman Liutikov10:05:00

We could probably take something from Reason’s website https://facebook.github.io/reason/

Roman Liutikov10:05:03

Interactive docs are super cool to have. React’s website is a good example https://facebook.github.io/react/

daveliepmann12:05:35

@mekza I think it could be a quick win to convert https://clojure.org/community/resources to look more like that Python wiki.

genRaiy13:05:16

Btw an alternative to Klipse which is lighter weight is paren-soup https://github.com/oakes/paren-soup/

Roman Liutikov14:05:20

FYI: I just posted this to gather a quick feedback https://mobile.twitter.com/roman01la/status/867743975104446464 I’m going to parse the feedback and put together a list of most commonly expressed concerns that could be possibly solved.

mekza16:05:22

> we do more as a community.

mekza16:05:25

it’s the key 🙂

john17:05:01

I think it's clear that Cognitect wants to ride a fine line between maintaining control over CLJ/CLJS while still being able to farm out community maintenance and development activities to the community itself. Cognitect can't do both - at least, not easily. And I tend to think that the development model is currently working well, despite perhaps some problems with expectations and messaging. So some community development activities can and should be maintained by the community. In order to build out that effort, I would think the participants would need to feel like they have greater ownership and control over that process - not needing to sign a contributor agreement or wait on the Cognitect to triage PRs for documentation updates, for instance. So, perhaps a good exercise, would be to discuss a clear delineation of responsibilities between cognitect and the "community," thereby allowing members to feel like they have more ownership over their part of the process and development of the community.

john17:05:52

My vote is for a community branded IDE based on Atom+ProtoRepl+ParInfer. That solution looks like a near-professional product, familiar to many developers and seems very friendly to newbies, in terms of complexity and presentation. Such a default beginner recommendation is one of the "missing pieces" that A) many beginners have pain with, and B) is an area that Cognitect probably won't (and probably shouldn't) provide an opinionated solution for.

john17:05:33

Personally, I use Cursive. I think I'd still recommend Atom for beginners though. A very valid path is to start with a simpler IDE and then graduate to more powerful ones (emacs even!) after beginners have acclimated to the language.

john17:05:08

I'm also in favor of leveraging klipse for some documentation purposes. I do wonder if the initial load phase can be improved to prevent the page lock that I've sometimes experienced with klipse (perhaps with a web worker?). But in general I think it's a genuinely helpful tool and it's just cool. 🙂

john20:05:35

A useful way to look at this: Clojure core is like the Linux kernel. The role of the community is to deliver a kind of Clojure Distribution that has user-land amenities that make working with the Clojure kernel a pleasure. It's not Linus' or http://kernel.org's job to deliver a beautiful userland, and, ideally, it wouldn't be Clojure core's job to deliver beautiful distributions of clojure. That's a userland concern.

john20:05:09

And while there are and should be many flavors and distributions of clojure, there needs to be an ubuntu of clojure distributions.