Blog tutorial: mention why to import JS files instead of using src attribute?

[caesiumtea]

So, I'm new to Astro and just going through the "build a blog" starter tutorial. It struck me as odd that "importing a .js file" instructs us to write an import statement between the <script> tags instead of what I would normally do, using the src attribute on the script tag. I asked for clarification in the Discord server and someone kindly explained how adding attributes to the script tag would disable Astro's usual way of processing those scripts. Personally, I feel like this an important warning to give to new Astro developers, since it's non-obvious that using attributes would have that effect.

My proposal is to add one of those "tip" callout boxes to this section, with a short warning that using src or other attributes may have unintended effects, and a link to the section of the docs that explains this in more detail. Do folks agree that this would be appropriate, or do you feel it would be too distracting in the beginner tutorial?

[sarah11918]

I personally feel that's more distracting than helpful? Many of our tutorial takers in fact do not have the knowledge of scripts you describe, and this is extra cognitive overload (and a warning!) that I don't feel they need at this time.

The point of the tutorial, which admittedly is already pretty long, is to allow people to firstly get through it successfully! 😅 We try to have as little friction as possible, and intentionally, as little explanation as possible because many things you will see by doing it that/how it works.

The goal is to have people have some initial success with something working, and have the vocabulary and experience to then be able to read and learn from the docs. It's intentionally light on extra content and explanations. In fact, some amount of confusion and curiosity by not having everything explained up front, prompting people to go check the docs themselves, is a good outcome!

If you're curious, this is the educational/docs model of a tutorial that we use as one of our pedagogical references when we design educational content!

I'm open to other opinions! But I do feel this falls into the distracting bucket vs the helpful bucket.