> On Mar 19, 2017, at 2:34 PM, Fenton Travers <fenton.trav...@gmail.com > <mailto:fenton.trav...@gmail.com>> wrote: > > https://www.reddit.com/r/Clojure/comments/5zu1oc/my_datomic_tutorial_feedback_sought/ > > <https://www.reddit.com/r/Clojure/comments/5zu1oc/my_datomic_tutorial_feedback_sought/>
My feedback: this is really awesome for several reasons! 1) I really like the direct, unadorned descriptions you’ve used. While I’m a huge fan of Clojure for the Brave and True (and its spiritual ancestor: why’s poignant guide to Ruby), and refer a lot of people on to those resources, for me personally I really need to be taken straight to the point. "You can think about the data that is stored in datomic as just a bunch of maps” - perfect, that makes it feel like we’re standing at a whiteboard together and you’re trying to move us along quickly. 2) I feel that there aren’t many Clojure resources that directly explain a feature in terms of a similar feature in other contexts or languages (with the exception of Java). So I really appreciate the contrasts you’re drawing with SQL, because it helps me as a practicing programmer to jump straight to understanding how things are different. It’s like giving me just the patch I need for my brain, not the entire repo. 3) Similarly, I like how you’ve made this contrast especially meaningful by highlighting two things. First, how Datomic solves a real pain point for me. I used to have to do SQL joins, which are ugly and tricky to get right, but now that pain is *gone*. Secondly, Datomic goes further by letting me do things that are basically impossible in regular SQL, namely, getting heterogeneous result sets based on “column” across the entire database. Boom, you just sold me on Datomic in a way that not much else has. Why do I think this is important? I believe we have a lot of resources that explain how Clojure solves problems experienced by Java developers, by highlighting contrasts like this, but not so much for other technologies. Most Ruby or Python programmers don’t feel the pain of concurrent programming and so spending a lot of time on immutable data structures doesn’t feel very “real” to them. This is a crucial hook for beginner tutorials targeted at working programmers, you need that hook that makes them say “Holy crap, that’s something new, and it totally solves that pain. I really need to learn this" 4) Putting the tutorial and the code together in the same repo is nice. It removes yet another barrier to entry, I know when I read “and all the source code is available elsewhere at http://…” I almost never bother to chase it down. Being able to say “and the source code is right under your nose” is always great. 5) I’m not sure if you thought explicitly about your pacing, but you did a good job here too. Take big concept, break it up into smaller concepts, then bring each concept into focus. Acknowledge to the reader that certain concepts will remain fuzzy until we revisit them, and don’t take too long before you do that. Having to revisit a topic isn’t just an awkward thing you have to work around, if it’s well written it’s actually another “hook” that will keep people reading because it’s enticing to learn more. 6) The style of “let’s try this and see what we get? Hmm not quite right, but we can now do this …” is reminiscent of how we interact at the REPL, but I don’t think you encourage the reader to fire up the REPL and follow along. Some people might not even realize this is a thing you can do. Dare I say it, but perhaps the Klipse plugin would be an exciting addition to a tutorial like this. One could imagine making the training more “real” by actually asking the reader to demonstrate their understanding by producing some data that “unlocks” the next part of the tutorial. Just a thought … All said and done, it looks like you put a ton of effort into writing this, and it was very worthwhile. I have already forwarded it to a bunch of colleagues who were Datomic-curious and had positive feedback. I hope you keep writing! Luke. -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
