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.

[OliverSpeir]

Using the src does not imply is:inline

https://docs.astro.build/en/reference/directives-reference/#isinline

The is:inline directive is implied whenever any attribute other than src is used on a <script> or <style> tag

I assume the original reason for importing in the script in the tutorial is to introduce users to the astro script processing which allows you to import from files within your src/ folder, and this is because of the bundling feature of Astros script processing as well as the fact that astro turns the script into type module automatically

Normally in a standard html script you would need to import from an actual file path that is served by whatever server is hosting the html page, and use type="module" but Astro handles this for us.

So if the goal is to reduce cognitive load and not introduce extra features it would be more intuitive to use the src