7 ms·

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

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.

thom 6y ago
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.
- spapas82 6y ago
  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.
  - MikeOfAu 6y ago
    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.
harperlee 6y ago
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.
- MikeOfAu 6y ago
  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).
  - hellofunk 6y ago
    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.
    - MikeOfAu 6y ago
      Thanks, I'll keep that in mind.
      - rboyd 6y ago
        the re-frame docs are great, never change
synthc 6y ago
This part: https://day8.github.io/re-frame/a-loop/#the-data-loop 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 6y ago
  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.
  - jb1991 6y ago
    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 6y ago
      I've lost track of how many times you have posted pretty much exactly the same thing. Seems slightly fixated.
      - hellofunk 6y ago
        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.
idointernet 6y ago
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).
- MikeOfAu 6y ago
  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.
  - idointernet 6y ago
    Definitely useful. Consider code examples just a missing leg in your table.
jb1991 6y ago
> In my experience, this an unusual opinion 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.
- pinchhit 6y ago
  > 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.
  - b4ke 6y ago
    then maybe the goal isn't to be a serious project in the context upon which you apply that classification.
- MikeOfAu 6y ago
  > 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.

thom 6y ago

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.

spapas82 6y ago
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.
- MikeOfAu 6y ago
  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.

harperlee 6y ago

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.

MikeOfAu 6y ago
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).
- hellofunk 6y ago
  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.
  - MikeOfAu 6y ago
    Thanks, I'll keep that in mind.
    - rboyd 6y ago
      the re-frame docs are great, never change

synthc 6y ago

This part: https://day8.github.io/re-frame/a-loop/#the-data-loop 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 6y ago
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.
- jb1991 6y ago
  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 6y ago
    I've lost track of how many times you have posted pretty much exactly the same thing. Seems slightly fixated.
    - hellofunk 6y ago
      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.

idointernet 6y ago

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

MikeOfAu 6y ago
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.
- idointernet 6y ago
  Definitely useful. Consider code examples just a missing leg in your table.

jb1991 6y ago

> In my experience, this an unusual opinion 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.

pinchhit 6y ago
> 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.
- b4ke 6y ago
  then maybe the goal isn't to be a serious project in the context upon which you apply that classification.
MikeOfAu 6y ago
> 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.