WA101: just the presentation

[rvedotrc]

I have realised that I'm not sure what I'm doing with #70. So, this PR is intended to simplify things, and get clearer feedback / make progress.

---

This module is intended primarily to take the form of a presentation.

There is a presentation; originally as Keynote, but also exported as PDF and as HTML. I was thinking that I needed to convert it to a more markdown-with-inline-images style, but now I'm thinking: why? Is the presentation alone sufficient? If not, what else is required, and why?

If the goal that we're trying to reach uhhh, yesterday (Sunday June 8th) is to have the modules with agreed content, structure, and not too far away from "ready to teach", then I submit that this PR is sufficient. And not only is it sufficient, it is less desirable to add lots of markdown text (at least, text that's aimed at the trainees).

[marcorichetta]

This module is intended primarily to take the form of a presentation.

There is a presentation; originally as Keynote, but also exported as PDF and as HTML. I was thinking that I needed to convert it to a more markdown-with-inline-images style, but now I'm thinking: why? Is the presentation alone sufficient? If not, what else is required, and why?

If the goal that we're trying to reach uhhh, yesterday (Sunday June 8th) is to have the modules with agreed content, structure, and not too far away from "ready to teach", then I submit that this PR is sufficient. And not only is it sufficient, it is less desirable to add lots of markdown text (at least, text that's aimed at the trainees).

Thanks for the content Rachel!

I think the presentation is a good starting point for a lesson-plan, specially because this is a entirely new module. We always can add assignments later on!

On the other side, I keep seeing a lot of assets (500+) committed and I'm not sure they're needed.
They seem like assets used by some other program but the PDF presentation should be self-contained (I believe).
If that's the case, everything under assets/ could be gitignored.
You can use git check-ignore to debug

[rvedotrc]

It's deliberate; it's the presentation, in HTML format.

Which is to say: I think it's a good idea to include the HTML format (with all these assets). It's a good delivery mechanism.

I'd agree that maybe marking the assets as "generated" might be a good idea, but I think it would be a bad thing simply to remove them.

[te-online]

Very neat! 😊

I've read the previous PR #70 and comments to get some context.

Here's some feedback on the presentation's contents and … ehm … presentation, in no particular order:

1. Amazing to see consistent use of the official example domains. And I like to see all the visual explanations with stick figures! 🤸‍♂️
2. I'm used to seeing "Frontend" and "Backend" as single words (I know, my dictionary disagrees). I'm not sure what I prefer, but "Front End" and "Back End" feel a bit "surprising" to me as spellings
3. It is technically correct, that https is the scheme of the URL. However, it could be beneficial to also introduce the term "protocol", because in my experience that is what most people use in their day-to-day spoken language. The protocol in this case being "Hypertext Transfer Protocol (Secure)" or "HTTPS". A co-worker, from my experience, is likely to ask "Which protocol are you using for your request? FTP or HTTPS?", but not "Which scheme are you using?". That being said, this may be too confusing, so if you think that it is, forget what I said above 😀
4. At least in the Keynote file, some section title slides are somehow in "skipped" mode in the presentation. Is that on purpose?
5. For the "How to see content-type / page source" slide, I'd recommend to write a flavor of "right click" -> "View Page Source" (HTML only) and "right click" -> "Inspect Element" (Developer Tools), which works in Firefox, Chrome and Safari (I assume Edge works similarly). Keyboard shortcuts are also somewhat aligned between browsers, but differ from Windows to Mac to Linux. Alas, in Safari one cannot simply do such things without extra steps 😭 First you need to go to "Settings" -> "Advanced" and choose "Show features for Web Dvelopers", see screenshot below.

Safari Screenshot

6. Slide 29 and 30 seem to be the same with different layout?
7. I think the "Cannot make network connections" is a bit misleading, because even though default CORS and CSP rules are tightening, much of the web still (somewhat unfortunately) sends data to external domains all the time. And we have iframes as well… If I was going to mention one thing, it'd be "Cannot keep secrets", even though that is hard to phrase in a good way. What I mean is, that you cannot put your password in HTML or JS, because it will leak (see Web Developer tools).
8. What is the difference between the backend-y and API-y exercises you're missing? And are you talking exercises for trainees or "demos" as can be seen in the frontend part? I'm wondering who could help with providing those?

---

Some more meta remarks to this PR:

• Assets—I like the idea of having the "source" of the presentation in the repo, if that is a thing that exists (?), but I tend to agree with @marcorichetta that the "web flavor" version of the presentation is adding a lot of noise to the repository. Especially, or maybe solely, because it is not really human-readable. I see why it can be beneficial to have something that can run in a browser, but at the price of having a lot of non-human-readable files in this repository? That being said, I think a short section in the Readme telling more about the different file formats, and how they were created, could go a long way of providing a bit of context for why this is here.
• Session format—I think the presentation is very good, I'd give it like that! The thing I'm a bit worried about is the "only presentation" format of the session. If we cannot add exercises, which I find fair – the HTML tree exercise always seemed a bit "artificial" – maybe we should add markers for breaks and/or generic exercises just to give trainees some opportunity to re-focus and re-charge. Of course, we could say this is the responsibility of the mentor, but it could be nice to have it documented, so no-one forgets it.

---

In general, very good work 🎉

I'd like to approve, but I'm a bit unsure if (1) you want to comment again on the format / generated files aspect, or if you said your piece on that, and (2) if you want to finish the TODO sections in the presentation before merging?

This is why I'll add this as a comment first 🤓

[rvedotrc]

I've replaced the HTML + assets by a single zip file.

[rvedotrc]

Effect of having the presentation in this format, of course — hard to add PR comments against specific lines of specific files. Hmm. Anyway:

• re. scheme vs protocol: I agree, and I thought about that when I wrote it, but yes it's worth mentioning protocol here as well.
• Frontend vs Front End, etc — I'm not fussed. I'll change it if there's a general consensus for that.
• skipped slides: yes, on purpose. The slides are there because they help me organise my thoughts while preparing this, but for the narrative (i.e. when presentating), it's better without them, I think. Hence they're skipped.
• For the grey "exercise" slides (e.g. view source), yes I had hoped that we could somehow crowdsource (for small values of "crowd") the answers on how to do things like "see the whole URL" in each of several major browsers.
• 29 & 30: yes, they are. This, too, is deliberate.
• network connections: I'll get back to you on that one...

As for the general structure of this material, and of the session as a whole: when I tried just doing the presentation talking to myself, I think it took maybe 30-40 minutes. So let's assume multiply by, say, 2.5 to account for the fact that I tend to present quickly, and the trainees will benefit from a slower, clearer delivery, potentially with lots of repetition. That makes it 90-100 minutes, just for the presentation. Then add time for repetition, questions, explanation, exercises, group discussion.

IMO this module is not complete yet, but it's a decent first go, and it gets us a pretty long way towards giving us a session that we can actually deliver as part of the course. Is it perfect? No. Should we merge it? Yes — I think it's better having this than having nothing.

Maybe once merged I / we could do a sort of "plan what's next" PR for this module. I know that I'm a few days overdue already (sorry!) so I suggest that it is better to merge early and often at this stage, rather than waiting for something more polished / complete.

[magdazelena]

so much great work put into this. I added some comments based on teaching experience, I hope they make sense.

[magdazelena]

we can use so many more things though - html, css + loads of advanced magic.

I understand what this means, but I'm worried that at this stage trainees take things very literally. Perhaps being more verbose could be useful, like:

Suggested change

	- we can only use JavaScript;
	- we use HTML & CSS to format and style documents
	- we use JavaScript to introduce any interactive logic
	- there is a variety of languages and frameworks available, but ultimately in the web all needs to transpile to JavaScript

[magdazelena]

Suggested change

	- the primary goal is to send back a response for each HTTP request;
	- we define the endpoints for the HTTP requests
	- we define what data can be send back to frontend per each endpoint
	- we define the structure of the data to be send to the frontend

again, for verbosity. It is the backend that defines the endpoints.

[magdazelena]

I think all of that is going waaaaay to deep for foundation to web dev. Just quantity of new names and acronyms in this recap is overwhelming. I can already see they synapses fry when mentor explains protocols or the binary cat picture :D

I'm no saying it's not relevant, because it is. I am concerned though about the retention of the focus. Knowing http protocol intricacies is not applicable at this level, therefore will not be retained.

what could be done instead is:

• explain what an endpoint is (address to call for data over network - metaphore prefered here)
• stucture of endpoint could be explained on domain + stuff basis, maybe with relevance to the systems paths so trainees have something to associate it with
• different types of requests (GET, POST, PUT, DELETE) - briefly, on metaphores. Payloads and such will come with backend implementation or frontend - i'm not even sure about this. I think this should come later too.
• I would put the communication tool AFTER explaining the layers it could communicate between
• you could consider consolidating all the great work you did with this module to a pre-read or a bonus read for the curious :)

[magdazelena]

that's if you actually discuss content type, which at this level i would advise against

[magdazelena]

why? How does browser work? What happens when I type url and I can see the page?

They don't know that at this level. On this level it is good to show a browser diagram or a metaphore to explain:

• that browser is just an advanced engine for displaying documents
• that it all started from displaying academic papers, like MS Word
• therefore the core of everything is HTML and what that is (some may not know even that!)
• that styling is done with CSS and it's also a scripting syntax
• you can, in fact, have the website with no js. Why do we need js then?
• bonus could be to show possibilities - yes, facebook or github are web pages, but so are web games (your example) or 3D three.js experiences (some example from FWA could be nice for wow effect).

I'm not saying my material is excellent but at JS2 I used these metaphores and trust me, there were questions :D
https://github.com/magdazelena/hyf-js2-week1

[magdazelena]

I also would like to argue that not at this point. I would put that into the advanced read, and talk more about:

• data
• security
• optimisation & communication between services
• modern backend in the workplace it's not going to be static server to display a website, it will be cloud architectures, systems, services -> still pointing to a frontend

If this is a foundation to explain what path each specialisation will open, I would advise against going into specifics, but rather showing the big picture on clear examples. Use of metaphores and in general reference to what trainees KNOW already is a great way to slide into their minds.

I would be thrilled at this level if someone explained to me how, idk, facebook backend works (of course in no details). Where is the data, how is it gathered, how does it even know it's me (auth). So much power and excitement there.

[magdazelena]

and this is where I would suggest communication layer (like I wrote in other comment)

[adamblanchard]

My suggestion for next steps, since @rvedotrc is handing this over:

1. I merge this PR in it's current state
2. I create a new PR and create/restructure the required md files (to match the structure of other modules)
3. @te-online @magdazelena You could then create PRs for any relevant changes you suggested here - that would be really helpful!

While it feels a bit wrong to merge while there are open questions/suggestions, i think it is the easiest way while we are taking it over, to keep things moving forward.

I'll start these steps now.

[te-online]

@adamblanchard Good plan!

• Did you already create the PR for 2.? Nevermind, I found it
• How should we edit the presentation? Which one is the source format?

[adamblanchard]

@te-online I'm sure it's the .key one, which can then be exported to pdf/zip.

For tweaks to the slides, of course they can and should be made in the presentation.

But for any content updates to the module, e.g. a new section, new assignments, new exercises etc. I think they should be captured in the markdown first (or at least, as part of the same PR).

In my view, the markdowns are the "source" of the module, and any presentations or other material that is created to support teaching the goals is an addition, since another mentor might come along and make their own slides for the same learning goals.