[synthc]

This part: https://day8.github.io/re-frame/a-loop/#the-data-loop The analogy with the water cycle is not helpful at all to me.

My background: I have several years of Clojure(script) experience, and used various other cljs frameworks before trying re-frame, so my view is probably biased.

[MikeOfAu]

And yet I've also had people tell me the opposite - they say they liked the water cycle analogy, even more than the subsequent dominoes narrative. Hmm. Hard to know what to do about such conflicting feedback.

[rjknight]

Very happy re-frame user here - I was pleased to see the 1.0 release recently and I like the sound of the new developments.

Personally I do appreciate the amount of conceptual framing (pun intended!) contained in the re-frame docs. It's one thing to know the syntax for, say, declaring a subscription, but it's something else to know what subscriptions are for. For me, Re-frame's value-add is that it provides a bunch of sensible patterns for structuring an app, so this stuff clearly matters more than it would for other libraries.

That said, I think some of the basic elements of how to use re-frame are harder to find than they should be. There's the instant gratification "just show me some code so I know what I'm dealing with here" problem, where I think people just want to see a bit of sample code in order to orient themselves.

Re-frame has a very positive story here, because the API is very concise: you could show registering an event and a subscription, and subscribing and dispatch in the view layer in maybe 15 lines of code. For a new developer, the understanding that the API is mostly just two functions and two macros makes the whole thing look much less intimidating.

The reference docs are also a bit tricky to work with. The generated docs tell you about functions that you will probably never call, and crucially the generated docs don't include built-in effects. I'm sure there is some documentation on how to use `dispatch-n` somewhere, but I'm damned if I can find it and so I normally just read the source code to remind myself.

[MikeOfAu]

Docs on builtin effects were added last week.

http://day8.github.io/re-frame/api/

Then click "Builtin effects" in the left Nav.

I'm actually working on the API docs at the moment and wrestling with codox and markdown interaction.

[rjknight]

Awesome, that's exactly what I was looking for.

[jb1991]

If you try to come up with lots of clever analogies and complex stories, layered with lots of self-congratulatory enthusiasm, some people will get it or like it, many will not.

On the other hand, if you write simply and just get to the point, everyone will benefit. Leave out the editorials and just say what needs to be said so developers can use their time on their code.

You could easily remove 80% of the words in all documentation about re-frame without losing the important content.

[MikeOfAu]

I've lost track of how many times you have posted pretty much exactly the same thing. Seems slightly fixated.

[jb1991]

It’s only because I have a lot of respect for the Clojure language and ecosystem as a whole, but I often see non-Clojure developers or only hobbyists refer to the community as pretentious and get put off by that, so I like to call out those things that are unfortunately adding to that impression. Sorry if I overdid it.

[MikeOfAu]

You are Tim Baldridge and I claim my five parens.