Clojurians Log v2
re-frame
I have created a new FAQ entry covering this: https://day8.github.io/re-frame/FAQs/FocusOnElement/
started reading it, I like the way it slowly explains Clojurescript on examples
Reading definitely takes much longer than 20 minutes, it took me about 20 minutes to get to Special forms
I would remove or postponed the section about quoting, not really needed there for anything.
Description of fn is quite hard to digest. I would maybe swap fn with def which is much easier to explain and then I would start fn with a few simple examples and I would follow with explaining the general fn on them.
The examples below with two starting parethesis might look strange to a beginner.
We need to make some changes:
(let [a "the pen"
b "a sword"]
(if (> a b) a b)) also "str" below was never introduced
I would also mention why using keyword as a function is better in general code, because if the map is nil, using it as a function will throw null pointer exception.
Maybe with a comment that you can also always use get when uncertain what is the map given in a symbol.
I would consider adding some real world examples for JS people before going into Data Functions, for instance how about showing hiccup as an example?
I like that the focus of this is to introduce slowly Clojure while explaining step by step how evalutation works (compared to just throwing examples at the reader), but it might be too slow and the reader might start wondering "how the hell is all this useful for my daily job"
I didn't finished reading till the end, but I would say this text would take at least 60 minutes to go thought when you haven't seen Clojure before
@mikethompson, here are my thoughts on the re-frame docs. there's a link to a pull request in the issue, https://github.com/day8/re-frame/issues/626
@pavel.klavik Many thanks for that feedback. I have integrated many of those ideas. But I have retained fn before defn for various reasons, I think that ordering might be difficult, but it ultimately pays dividends.
@smith.adriane thanks also, will address your suggestions via the PR
looks great! two suggestions which are really just one. I've found some the re-frame documentation hard to skim or find specific answers when the subheadings are similar with just numerical differences. Here's what I was thinking: • change the title "Answer #1" to "Answer #1 - HTML autofocus" • change the title "Answer #2" to "Answer #2 - Reagent after-render"
@smith.adriane Good idea, thanks.
It's really nice using a library with great docs 🙂! I've been getting a lot of use from the docs recently. I wrote some notes that I can try and summarize to hopefully be useful.
Please do
A couple of decades ago, I wrote commercial courseware (for about 5 years, during a slacking-off phase of mine). But at that time I had the advantage of immediately road-testing my courses on new people, and noticing what worked and did not. It was constantly shocking the misunderstandings which were possible. But at least they were quickly corrected through near-instant feedback. It is so much harder when you write docs in Github. Almost Zero feedback. I'm quite sure there are problems with the presentation of ideas, but without the feedback I'm blind to them.
Re-frame docs are probably one of the best docs I have ever read. Especially the introduction is great, I was very quickly convinced to start using it.
What I am missing is coverage of some more advanced topics, with connections to Reagent. I will likely try to write something down in OrgPad (http://orgpad.com).
Because people so often come across from javascript ... I have been slowly building up a way for them to ramp up ...
Top secret ... don't tell anyone :-)
Still WIP, quality falls away at the very end
Next I have to do something likewise for Reagent as you suggest