Hmm. In my experience, this an unusual opinion (to me, the author). Over the years the re-frame documentation has been the most praised part of the project.
Could you point out the area which you found unnecessarily difficult, and I'll happily review it. Could you also include your background, so I know where you are coming from? The docs are a little oriented towards JS developers coming across, but perhaps you are already very experienced with Clojure and data-oriented design, which makes it seem like the concepts more obvious. Maybe.
Said with love, happy re-frame user: many developers want to be able to match use cases to docs and code examples as quickly and directly as possible. The re-frame docs contain a lot of very verbose motivation and philosophy (over multiple pages) which while useful context, obfuscates the practical content. All of re-frame’s philosophy would be immediately evident from some code examples on the top level readme on GitHub.
This is on point. Whenever I have tried reading the re-frame docs (I actually have tried more than once during the prevt years) I always get frustrated/bored from the lack of actual use cases and explanations of why this could be useful to me!
The docs just seem to academical for me... They would be excellent for a master's thesis but not for somebody deciding if he would like to invest time into a project.
Thanks for the feedback. In this regard, I think things have improved a little over the last 8 months, stepwise.
In our busy world, people want more immediate summaries and progress. These docs arose out of me trying to teach my team how to think about coding in Clojure and to use re-frame (we were all new to the language at the time), so they definitely have a didactic flavour.
I continue to nudge them in the direction you recommend.
It can't be too unusual; I've seen this critique shared in forums, to which you've replied, for years.
I've seen developers remark how turned off they got by reading stuff like this on its front page, which is frankly just noise and undermines the goals of a serious project:
> re-frame is lucky enough to enjoy an unfair advantage...When we use Lisp, we get to leverage 50 years of foliated excellence from the very best minds available.
I mean, come on. The very best minds work in many different fields with many different languages. Lisp doesn't own the best minds, and neither does re-frame. The fact that lisp or Fortran or other languages have been around for many decades is kinda irrelevant, and this writing style permeates all the docs.
> Travel the geodesic.
> an immaculate hammock conception
The heart of the how-tos is often hidden in lengthy prose that celebrates itself.
> It can't be too unusual; I've seen this critique shared in forums, to which you've replied, for years.
In this thread, I was responding to someone saying the concepts were simple but explained with too many buzzwords. I certainly have no recollection of someone of someone saying that before.
On the other hand, I have heard some say they'd want more code examples earlier. And, just as soon as I get time I'll be doing that. Unless you want to supply a PR yourself - given your posting frequency you seem very, very invested.
> I've seen developers remark how turned off they got by reading stuff like this on its front page, which is frankly just noise and undermines the goals of a serious project:
This was exactly my experience. Professional clojurescript developer using re-frame, but not typically one to chat on forums. I wouldn't have shared this opinion until prompted to by this forum, but it's an opinion I've held privately for longer.
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.
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.
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.
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.
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.
I’m another person, but: when I initially read an old version of it (about 4 years ago) I liked the comprehensiveness but disliked the tone. Perhaps due to not being a native english speaker, it distracted me and made it harder to get the point.
Quickly peering it it seems that it has been improved, although some things there remind me of what I felt, such as:
McCoy might report "It's MVC, Jim, but not as we know it". And you would respond "McCoy, you trouble maker, why even mention an OO pattern? re-frame is a functional framework."
This does not help me a lot; although I know about “the real mccoy” expression, I dont understand/enjoy that.
Well, I'm glad to hear it might have improved. After taking a battering in this thread, I'll take any possible small win.
What you reference is an attempt at a joke which requires certain cultural knowledge (Early Star Trek). On this point, I'm probably unlikely to change, and will just have to ask for your forgiveness. I like my docs to have an occasional joke, whether I'm the reader or the writer. But I am aware that this is not everyone's cup of tea (English cultural reference).
The re-frame docs and "marketing" speak, like on its front github page, would do very well to remove a lot of the self-congratulatory tone, frankly. A lot of it reads like someone very impressed with themselves rather than text about how to use an actual tool.
I really like the re-frame docs, thank you very much for putting so much effort into them. They've helped me grow as a programmer. For context, I first stumbled across the readme in ~2015-16 in college before working professionally. As someone looking to learn I enjoyed the didactic bent, I felt like I got the big picture. It tied together a lot of Clojure kool-aid.
The vibe I get from the tone of the docs isn't really juvenile or self-congratulatory. The humor is mature, references made show that material therein have been considered. It's not memes and emojis and WOW! It's somewhat unprofessional, has a few in-jokes, but I like those signals. If the docs haven't succumbed to design-by-committee lowest-common-denominator then neither has the code. It gives me the feeling that someone took the slow road, thought about a lot of things, came out with something simple, and is likely to work hard to preserve that simplicity.
The docs tell me that re-frame is focused on the craft. That means a lot more to me than sprinting to see how do I do x in y quickly.
Please don’t listen to the peanut gallery. The re-frame docs are in a league of their own and most of us appreciate the enormous effort put in to make them awesome. Keep rocking.
The docs are great and re-frame is a pleasure to work with. It make take some time to read through the docs but it is a worthwhile endeavor as the concepts build upon each other. They reward those willing to take the time. When I was a newcomer to re-frame and cljs I did not find the re-frame docs to be pretentious or off putting in any way. If not for re-frame and the re-frame docs I'm not certain I would have continued to use Clojure or cljs. Thank you for building this excellent tool and providing high quality documentation to back it.
Well I tried to write a balanced comment and try not to hurt but it seems I failed. As I said, the content was good; and I did not say it but I would kill for that level of docs in every open source project. So sorry if I hit your emotions and thanks for your work!!
I'm a react developer and I immediately wanted to see code examples. I looked through the docs and couldn't easily find any. I went to the API docs on mobile and was met with layout issues (iphone 11 on Chrome).
If those code examples were in an unfamiliar language (ClojureScript), would they still be useful? I've been under the impression that the concepts would have been a more helpful in that case.
Could you point out the area which you found unnecessarily difficult, and I'll happily review it. Could you also include your background, so I know where you are coming from? The docs are a little oriented towards JS developers coming across, but perhaps you are already very experienced with Clojure and data-oriented design, which makes it seem like the concepts more obvious. Maybe.