Ms Boba's Extra Notes from Writing the Learn-Along
Notes from my [Ms Boba’s] review of our learn-along, that show changes I made and how I
came to them. I had to formulate principles post-facto, as I never really
spelled them out before.
I had already seen (and written part of) the writing beforehand. Hopefully
this will help me get it right quicker myself next time—I keep forgetting
this is how we write.
Write to the audience: Address the reader directly, set clear
expectations, and anticipate questions they may have. Talk about different
ways they might approach the material.
Call to adventure: You’re telling the tale of a valiant hero that is about
to go embark on a trecherous journey, and your language should reflect that.
Note that this doesn’t mean that itself JavaScript is treacherous: it’s just what
Boba-tan tells herself to psych herself up.
Group related content, don’t change “subject”: Paragraphs and sections
often serve specific purposes. Don’t let unrelated notes slip in: move them
around, or reframe them so they match their surroundings.
Remind them they cannot fuck up: People will be worried about fucking up
and irreversely damaging something. If you can, reassure them!
This guide is best tackled with some familiarity with basic
programming concepts, like variables, if statements, and loops. While
we'll go over some of these concepts, you might want to use your
favorite search engine to look up things you're not familiar with. For
beginners that learn well by doing, we hope that fiddling with this
program will help you build a mental model of how programming works in
practice!
Some concepts that you'll encounter during this tutorial and
you might want to read more about (either before or after it),
include:
...
Things I notice:
“This guide is best tackled with some familiarity” => overly formal, impersonal
“While we’ll go over some of these concepts, you might want to use” => why so
tentative? be more decisive
“For beginners that learn well by doing,” => Feels like switching to a different
topic. Why is this in pre-requisites? Also, what if someone doesn’t identify
with the word beginner? Does this not apply anymore?
“we hope that fiddling with this program” => we do not hope! We know!
As you journey through this program, you can follow the path from
start to finish, or skip around to what piques your interest. For
those who learn best by doing, fiddling with the code as you go will
help build a mental model of how JavaScript works in practice.
Remember: you can always download this file again (or use Git!) to
start from scratch.
If the comments feel overwhelming or in the way, you can use the
uncommented version of this file to follow along the code.
If you haven't explored programming yet, you can skim the guide to
see what's possible, and what you should learn on the way to your
goals.
### PRE-REQUISITES ###
This guide assumes you're acquainted with the building blocks of
programming, like variables, if statements, and loops. While we'll
give you some refreshers, make sure to use your favorite search
engine to look up terms you're not familiar with!
Concepts you might want to read more about on your own (either
before, during, or after) include:
Things changed:
Straight up made a new section. It came natural as I was thinking about what
the sentence that felt out of place was trying to do. I actually wrote
these parts separately in various sections, and then realized they were all in
the wrong place and belonged together.
Added a callout for “beginners” (without using the word). “Haven’t explored
programming” is less ambiguous, and keeps the adventurer feeling. We should also
be honest that this is going to be a lot, but not deter those who might want
to try. Framing it as “check it out and see what comes up” feels a good
compromise.
Other stuff I might change:
I still feel iffy about “you can use”, “you can skim”, but I’m keeping myself
from fiddling further.
I feel strongly about this one, so it gets its own place:
Add concise explanations to lists: when presenting lists of concepts or
terms, add a very brief description to each item, to help people understand
what it is and why it’s there. This provides context and helps learners feel
less lost.
Frame challenges as fun, approachable, and within the person’s reach: When
a task feels overwhelming, try thinking about what could make it easier for
them and where they’re likely to get stuck. Try getting them “out of their own
heads”.
Normalize struggling with code, and encourage a growth mindset: Where you can,
offer suggestions on how to tackle a task, and remind people it’s ok to struggle
or come back to it later.
As you make your way through, you'll find a few [[EXTRA CREDIT]]
callouts scattered around this guide. These are optional exercises to
help you learn even more useful tricks!
Here's one for you to come back to:
[[EXTRA EXTRA CREDIT]]: After you've poked around this code,
it's time to add your own flavor of fortune cookie. If you need
inspiration, you can use your favorite characters, quotes, or even
random words.
Remember: when it comes to programming, a bit of practice goes a long
way—the challenge (and, sometimes, confusion) is part of the fun!
Important bits:
“scattered around this guide” => Makes it fun to find them
“to help you learn even more useful tricks!” => Explain why you’d want to
bother with them
“After you’ve poked around this code,” => Trying not to imply one has
to have understood it. People might understand from poking around, so
we shouldn’t stop them.
“If you need inspiration, you can use your favorite” => I’m anticipating
people overthinking what should go in the fortunes rather than just
putting something there.
“the challenge (and, sometimes, confusion) is part of the fun!” Keep
normalizing confusion. People will never escape it.
The above is what I ended up with, but I had a previous review I worked
up from. From that I got:
Keep it casual: Not too casual, obviously. Try embodying “the
fun (and slightly over-the-top) teacher people look back to fondly.”
Create a sense of dynamism: You’re gooooing somewhere! You’re doing
things, poking around, messing shit up! You’re a menace and no one can
stop you.
Confident, action-oriented language: Covered a bit before, but again:
project confidence! You don’t try, you succeed! (note: TBF, i’m not sure
I always keep this)
This was already with Ms Boba’s review, before being subjected again to her whims:
Throughout this guide, you will find some [[EXTRA CREDIT]] sections. These
optional exercises are interesting challenges that will help you learn
even more fun (and useful) tools!
Here’s one for you to come back to:
[[EXTRA EXTRA CREDIT]]: After you got a sense of how this program works, try
adding a new flavor of fortune cookie. You can use your favorite fandom,
quotes, or even just some random words. Remember: when it comes to
programming, a bit of practice goes a long way—the challenge (and, sometimes,
confusion) is part of the fun!
What I notice:
“Throughout this guide, you will find some [[EXTRA CREDIT]] sections.” => kinda
boring?
“These optional exercises are interesting challenges…” => Convoluted sentence
that feels like it could be streamlined.
“After you got a sense of how this program works,” this sounded weird, but
again I was trying hard to not imply people had understood it all.
“You can use your favorite fandom,” => I ended up with “if you’re feeling stuck”,
which qualified why i was saying this
“Remember: when it comes to…” => Moved it to its own line. This goes back to
making sure a paragraph sticks to its purpose. In this case, the encouragement
works well on its own, and doesn’t add unnecessary cruft for someone reading the
challenge.