feedback from reviewing Easy EdgeDB while onboarding

[zackelan]

overall feedback:

• I started off intending to follow along closely with the book, and actually run every query & code sample on my local instance. this hit a snag pretty early on, because there are lots of places we give examples of the schema definition evolving, but we haven't taught the reader how to do that sort of schema migration
  • first example of this is chapter 1, the Links section, "now the last thing left to do is to change our property in Person called places_visited to a link"
  • from least work to most, the options I can think of are:
  • mention this up front, and give instructions on how to give yourself a clean slate (DROP DATABASE and recreate being the easiest).
  • perhaps, we could do something like color-code the different code blocks, one for "don't actually run this" and one for "run this in your live instance"
  • as we come up with changes to the schema, give actual migration commands for it

chapter 1:

• "Lastly, we need to do a migration" - give me a copy-pastable code block here, I had to go look at other documentation to get the syntax right
• because I had to fiddle with the migration syntax, I hit a quirk of the CLI that makes it easy to lose edits to a multi-line command. repro steps:
  • submit a multi-line command with a syntax error of some kind in the CLI
  • get an error, hit up-arrow to bring the command back, then edit the command to fix the error
  • try to submit the command again by hitting enter. oops, that doesn't work, because I'm still in the middle of the command, so it just inserted a newline in the middle
  • down-arrow to go to the end of the line...but oops, I hit the down arrow one too many times, so it went back to history-navigation mode and gives me a blank cursor
  • if I hit up-arrow to get the command back, I've lost my edits and have to re-do them
• because I'm running each command it gives me, I had multiple Jonathan Harker rows by the end of the chapter. this surprised me for a moment, then I realized it's because I don't have a unique constraint. might be worth calling out as a possibility here, as well as a mention that it will be fixed in a future chapter (7)

chapter 5:

• "This is because float types on computers become imprecise after a while" - the YouTube video this links to is no longer available

chapter 6:

• when we show the JSON output for the first time, I think we should explain it, because it looks weird at first glance with all the escaping. specifically the outer curly braces are the EdgeDB set, not JSON brackets, and the outermost double-quotes are an EdgeDB string, and then the JSON string is inside it, with all the other double-quotes escaped. maybe show the "normal" JSON first, and then how it appears as EdgeDB query output?
• Q3 - this is a bit confusing, because it says that LIKE takes a string, but we're giving it a set of strings, and I don't think we've explicitly explained at any point the set-expansion that's taking place

chapter 13:

• Q4 & Q5 - these answers are a bit confusing, I think they would benefit from actually walking step-by-step through the Cartesian multiplication of the sets, then the DISTINCT, and finally the addition

chapter 16:

• Q4 - it gives me a hint to use str_repeat, the answer should include the query using that method

[1st1]

Some good feedback here. @vpetrovykh Victor let's fix some of the low hanging fruit here first.