I really dislike the documentation of re-frame.
The concepts are quite simple, but the docs explain them in a really confusing and buzzword heavy way.
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.
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.
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.
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."
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 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.
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.
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.
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.
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.
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.
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.
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.