ANN: I wrote a beginner datomic tutorial I wanted to share with y'all, constructive feedback welcome

[Fenton Travers]

https://www.reddit.com/r/Clojure/comments/5zu1oc/my_datomic_tutorial_feedback_sought/

[Alan Thompson]

Looks like a good start.  If you are interested, you may find some of the examples and helper functions from the Tupelo Datomic library useful:

https://github.com/cloojure/tupelo-datomic

Alan

On Sun, Mar 19, 2017 at 2:34 PM, Fenton Travers <fenton....@gmail.com> wrote:

https://www.reddit.com/r/Clojure/comments/5zu1oc/my_datomic_tutorial_feedback_sought/

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@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+unsubscribe@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+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Luke Burton]

On Mar 19, 2017, at 2:34 PM, Fenton Travers <fenton....@gmail.com> wrote:

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.

[Gregg Reynolds]

just starting on it but since you asked: the toc links do not seem to work, at least not on my android phone. also fwiw i would suggest a direct link, not a link to reddit, which some of us do not use.  better imho to post a note to clojurians on slack.

On Mar 19, 2017 4:34 PM, "Fenton Travers" <fenton....@gmail.com> wrote:

https://www.reddit.com/r/Clojure/comments/5zu1oc/my_datomic_tutorial_feedback_sought/

[Gregg Reynolds]

if you post a note to clojurians, we can give you editorial feedback useful to you but very boring to everybody else.  example: instead of "...we have to specify ahead of time which keywords entities in datomic are allowed to use" i suggest sth like "... which keywords may be used by datomic entities... " 

[Fenton Travers]

@Alan Thompson:

Yes I can see tupelo does indeed remove unnecessary
boilerplate.  That is good to know!

-----------------------------------------------------------------------

@Luke Burton:

Thank you so much for your encouragement, I did indeed
work many days on that.  I guess it matches my learning style.  I find
much of the documentation out there, quite difficult to learn from.
Its a never ending source of frustration for me.

You are quite talented in communicating, and I would grateful for you
to review any future work if you have time.  My next target is om-next
in combination with datomic.  Unfortunately, I find om-next to be even
more impenetrable than datomic! :(  So it may take quite a bit more
time before I'm able to produce anything of value.

Thanks again for your encouragement, it actually makes a big
motivational difference!

-----------------------------------------------------------------------

@Gregg Reynolds:

Okay, I'll post to clojurians on slack.  I know somepeople get upset
about cross posting on channels.  I'm really not sure of the
etiquette.  I did post to the datomic channel on slack.  Maybe I
should have posted to the clojure channel?

-----------------------------------------------------------------------


On Sunday, March 19, 2017 at 2:34:16 PM UTC-7, Fenton Travers wrote:

https://www.reddit.com/r/Clojure/comments/5zu1oc/my_datomic_tutorial_feedback_sought/

[Gregg Reynolds]

On Mar 21, 2017 12:43 PM, "Fenton Travers" <fenton....@gmail.com> wrote:

@Gregg Reynolds:

Okay, I'll post to clojurians on slack.  I know somepeople get upset
about cross posting on channels.  I'm really not sure of the
etiquette.  I did post to the datomic channel on slack.  Maybe I
should have posted to the clojure channel?

they're pretty forgiving. you might post an fyi to the clojure channel referring people to the datomic channel.

g

-----------------------------------------------------------------------

On Sunday, March 19, 2017 at 2:34:16 PM UTC-7, Fenton Travers wrote:

https://www.reddit.com/r/Clojure/comments/5zu1oc/my_datomic_tutorial_feedback_sought/

--