Incrementalize tutorial doc

[mahmoud]

Right now the tutorial is coherently designed, tested, and even documented. However, it doesn't build up in a way that's very beginner friendly. It establishes glom's value and then immediately uses it at an intermediate level.

I'd like it if it was a bit more drawn out to use basic features first and then add a multi-line Coalesce as the finisher. The announcement blog post does a better job of this, but doesn't go far enough before jumping ahead to T.

[dfezzie]

Do you want some more examples inserted into the current tutorial or using the announcement blog as the new base?

If you want to keep the current documentation, more examples could be inserted between Access Granted and Point of Contact. Could dive deeper into the basic features like in the announcement tutorial and then go into the API response example.

I like the flow of the announcement blog, but would need to be tweaked to fit with the API example.

Thoughts?

[mahmoud]

Hey @dfezzie! Thanks for your interest! I'm definitely interested in continuing with the Contacts example, as it kinda simulates the ORM nicely. If we could merge the approach of the announcement post with content of the Contacts example that would be ideal.

I think maybe there ought to be a tutorial pt 2 or something to get into T and Inspect and other fun stuff, but maybe I'll save that for another issue :)

Thanks again!

[onprema]

hey @mahmoud -- I discovered glom last night after seeing your lightning talk at PyCon. I love it! Is this issue still relevant? I'd like to contribute in some way and this seems like a good starting point.

[mahmoud]

Thank you for the kind words, @eightlimbed! I definitely think the tutorial could use more work! Last thing I did was put some interactive repl.it terminals in there, but they don't necessarily make it a smoother ride, understanding-wise.

I'm very interested in the perspectives of new users like yourself. We can use this thread to discuss where you feel friction and how we can improve the tutorial to make it better. :)

[onprema]

Ok, I'll give you my unfiltered thoughts when following the current tutorial.

• I open up an ipython session and type from glom.tutorial import * -- Now what? How do I start glomming along?
• The repl browser examples are kinda cool, but I prefer to follow a text tutorial and play around with it in my terminal or IDE
• ~Well, the embedded REPL examples aren't working. When I click "run" it shows no output in the terminal~. (it finally showed up, just took a while). When I click on the external link to repl.it, the examples work but it takes a long time to install dependencies and do whatever they are doing under the hood to execute the python code
• I actually like the way the tutorial is written.. it's kinda fun to read and flows well
• I wish the examples looked like this:

  target = {
  'system': {
  'planets': [{
    'name': 'earth',
    'moons': [{
      'name': 'luna'
      }], {
     'name': 'jupiter',
     'moons': [{
       'name': 'io'
      }...
  ]

  instead of

  >>> target = {'system': {'planets': [{'name': 'earth', 'moons': [{'name': 'luna'}]},
  ...                                  {'name': 'jupiter', 'moons': [{'name': 'io'},
  ...                                                                {'name': 'europa'}]}]}}

To me, it's easier to tell what's going on when the nested data structures are more vertical. I know it takes up more lines of code, but I think it's more visually appealing and easier for beginners to understand what glom is doing

• I feel like the "Point of Contact" example is a good example that is more comprehensize, but the heading should be something like "A more advanced example" or something like that. Some of the headings in this tutorial could be clarified... Like "Access Granted" might be "Accessing Data in Nested Dictionaries" -- Sure, its not as "fun", but at least I know what I'm going to learn when I read the table of contents

This feedback comes from a place of respect... Please take it with a grain of salt. I don't mean to knock what exists, but just want to say what is going on in my mind as a first-time user :)

[mahmoud]

Great points!

• I'm glad you found it fun to read overall :)
• As far as glomming along, I guess the thought is that you could copy and paste (or retype) the code samples yourself. It was actually thinking more about this that made me put in the interactive prompts with the code precopied.
• Speaking of which, yes, the repl.its are slow, and a little buggy, too. I'm hoping they improve.
• Re: reformatting, I think I agree with you. I'd accept a PR that made them more vertical.
• I agree about the headings. I'd also accept a PR with those changed (maybe we keep the originals -- at least the fun ones -- italicized underneath, like "AKA Access Granted")

So, were there any bumps along the learning path? Don't worry about being overly critical, fresh eyes is what this tutorial needs :)

I was mulling it over about a month ago, and I came up with some slightly new angles for a talk I was giving at a meetup in San Mateo. Slides here.

Slide 19-23 highlight a key missing link in the tutorial, I think: "Why does glom accept non-string objects as specs? Why is it more than just a deep-get?" I think there's an extra section or at least an aside that should be added, what do you think?

[onprema]

Thanks for sharing the slides @mahmoud -- I still have some thinking to do about the questions you asked regarding slides 19-23, but I wanted to get the changes you suggested in just to keep the ball rolling, so I submitted a PR for those.

I think the biggest bump for me now is in the "Point of Contact" section. When I read,

We’re implementing a Contacts web service, like an address book, but backed by an ORM/database and compatible with web and mobile frontends.

My eyes start to glaze and I feel information overload. I think "We're implementing a Contacts web service" is enough.

This code block is a lot to take in...

>>> spec = {'results': [{'id': 'id',
...                      'name': 'name',
...                      'add_date': ('add_date', str),
...                      'emails': ('emails', [{'id': 'id',
...                                             'email': 'email',
...                                             'type': 'email_type'}]),
...                      'primary_email': Coalesce('primary_email.email', default=None),
...                      'pref_name': Coalesce('pref_name', 'name', skip='', default=''),
...                      'detail': Coalesce('company',
...                                         'location',
...                                         ('add_date.year', str),
...                                         skip='', default='')}]}

I know that it is broken down line by line in the next section, but yeah, it's a lot. Perhaps a simpler example would be easier for the reader.

In the following section where this spec is broken down it consists of 5 blocks of text, which I also find kind of painful to look at. I would prefer to see something like...

For primary_email we see our first usage of glom’s Coalesce feature.

 'primary_email': Coalesce('primary_email.email', default=None),

Much like SQL’s keyword of the same name, Coalesce returns the result of the first spec that returns a valid value. In our case, primary_email can be None, so a further access of primary_email.email would, outside of glom, result in an AttributeError or TypeError like the one we described before the Contact example.

I want to be reminded of where I used Coalesce in my spec.

Does that make sense?

Hope you are having a nice weekend. I dig the trailer park boys references :P

[mahmoud]

Hey! I'm glad someone appreciates the TPB :)

I agree on "We're implementing a Contacts web service" being more approachable, and everything else for that matter, too.

As far as slides 19-23, all I mean is, I think most people find the string-based "deep-get" use case natural. How do I more naturally transition into passing more complex, non-string specs to glom(). But even if you leave that to me, the points you make certainly merit a PR on their own.

[onprema]

hey @mahmoud -- just a friendly reminder about this. hope you are doing well.