Fork me on GitHub
#re-frame
<
2020-07-03
>
mikethompson00:07:51

I have created a new FAQ entry covering this: https://day8.github.io/re-frame/FAQs/FocusOnElement/

👍 15
phronmophobic00:07:55

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"

phronmophobic00:07:03

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.

mikethompson00:07:12

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.

💯 3
Pavel Klavík03:07:32

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.

Pavel Klavík03:07:16

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).

mikethompson03:07:48

Because people so often come across from javascript ... I have been slowly building up a way for them to ramp up ...

mikethompson03:07:58

Top secret ... don't tell anyone :-)

mikethompson03:07:07

Still WIP, quality falls away at the very end

mikethompson03:07:01

Next I have to do something likewise for Reagent as you suggest

Pavel Klavík13:07:58

started reading it, I like the way it slowly explains Clojurescript on examples

Pavel Klavík13:07:20

Reading definitely takes much longer than 20 minutes, it took me about 20 minutes to get to Special forms

Pavel Klavík13:07:48

I would remove or postponed the section about quoting, not really needed there for anything.

Pavel Klavík13:07:41

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.

Pavel Klavík13:07:23

The examples below with two starting parethesis might look strange to a beginner.

Pavel Klavík13:07:18

We need to make some changes:

(let [a  "the pen"
      b  "a sword"]   
  (if (> a b) a b)) 
evaluates to `"a pen"`. Should be "the pen" at the end 🙂

Pavel Klavík13:07:49

also "str" below was never introduced

Pavel Klavík13:07:00

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.

Pavel Klavík13:07:02

Maybe with a comment that you can also always use get when uncertain what is the map given in a symbol.

Pavel Klavík13:07:10

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?

Pavel Klavík13:07:46

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"

Pavel Klavík13:07:34

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

phronmophobic20:07:23

@U051MTYAB, 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

mikethompson12:07:53

@UFHE11C83 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.

mikethompson12:07:38

@U7RJTCH6J thanks also, will address your suggestions via the PR