DEV Community: Megan Sullivan

Quick Wins to Make Your Content More Accessible

Megan Sullivan — Fri, 17 May 2024 05:23:48 +0000

Introduction

It's Global Accessibility Awareness Day (GAAD)! The goal of digital accessibility is to enable users with disabilities to independently engage with content and technology. Ultimately, it's about empowering disabled people to live with autonomy and dignity.

The World Health Organization estimates that 16% of the world's population has some kind of significant disability. As of 2024, that's 1.3 billion people.
In 2024, The WebAIM Million—an annual report on the accessibility of 1 million different websites—found that 95.9% of home pages had accessibility issues.

Accessibility issues prevent disabled users from accessing digital services and participating in online communities. Some accessibility problems require a developer to fix, but others can be fixed by anyone who creates online content! Here are three quick ways that you can make your digital content more accessible.

Note: This post references the Web Content Accessibility Guidelines (WCAG), which define standards for creating accessible web content.

The WCAG standard includes a detailed list of success criteria that a website must meet in order to be considered accessible. These success criteria are categorized into different levels:

Level A (the bare minimum)

Level AA (the industry standard)

Level AAA (above and beyond)

For your site to get level AA conformance, it must meet all the level AA success criteria and all the level A success criteria. Similarly, to get level AAA conformance, your site must meet all the success criteria for levels AAA, AA, and A.

The WCAG documents can be overwhelming at first! But they're also the industry's go-to resource for in-depth accessibility standards, so it's worth exploring them. For a more general introduction to accessibility, check out the W3C WAI Accessibility Fundamentals Overview.

Tip #1: Use Sufficient Color Contrast

The most prevalent issue reported in the 2024 WebAIM Million was insufficient color contrast.

For online content, color contrast refers to the difference between the color of your text and the color of the background behind it. With some fancy calculations, you can calculate the contrast ratio, which tells you how different your foreground and background colors are from each other.

Expand for accessible image description

	Low contrast	High contrast
Foreground color	#FFFFFF	#FFFFFF
Background color	#5492FF	#FFFFFF
Contrast ratio	3.02:1	15.05:1

Use a higher contrast ratio to make your site's text legible to users with visual impairments (e.g., cataracts or color blindness). The Web Content Accessibility Guidelines include the following requirements color contrast ratios:

Success Criterion 1.4.3 Contrast (Minimum) (level AA)
- 4.5:1 for text (and images of text)
- 3:1 for large text (18pt regular weight, or 14pt bold weight)
Success Criterion 1.4.6 Contrast (Enhanced) (level AAA)
- 7:1 for text (and images of text)
- 4.5:1 for large text
Success Criterion 1.4.11 Non-text Contrast (level AA)
- 3:1 for user interface components (e.g., buttons, form elements, or other page controls) or graphical objects (e.g., icons, charts) that are required to understand the content

Based on these criteria, the low color contrast example from the previous image passes 1.4.3 for large text, but fails it for small text. The high contrast example passes 1.4.3 and 1.4.6 for both large and small text. Both color combinations pass 1.4.11 for non-text elements.

There are a wide variety of online calculators you can use to determine the contrast ratio between two colors. Some examples:

WhoCanUse: Simulate what color combinations look like to users with different kinds of visual impairments.
WebAIM Contrast Calculator: Use an eyedropper color picker to select a color from anywhere on your screen. (This is helpful if you don't have access to the hex codes for the colors you want to test.)
Polypane Color Contrast Checker: If the color combination you tested fails one of the WCAG success criteria, it will suggest an alternative color to use instead.

Learn more about color contrast: WebAIM: Contrast and Color Accessibility

Tip #2: Add Alternative Text to Images

Images are great for creating engaging websites. They can also be helpful tools for helping readers understand your content. But what happens for non-sighted users who can't see images?

Many users with visual or learning disabilities use an assistive tool called a screen reader to navigate their computers. A screen reader is a program that translates the text and elements on the screen into audio, so users can hear the page instead of (or potentially in addition to) see it.

Want to see how it works? Check out this video by the Chrome Accessibility team: Screen Reader Basics: NVDA -- A11ycasts #9

NVDA is only available on Windows computers. Apple computers come with their own built-in screen reader called VoiceOver.

You can provide descriptions for screen reader users by adding alternative text (also called alt text) to your images. When a screen reader user moves their focus onto an image, the software announces the image by reading out the alt text.

How do you add alt text to an image?

If you have access to the underlying HTML for your page, you can add alt text to your image tag like this: <img src="myImage.jpg" alt="Put your image description here" />
If you're writing your content in a word processor or content management system, do a quick search on Google or YouTube to see how to add image alt text in your particular tool.

Note: There are certain scenarios where you don't need to provide alt text for an image. Check WCAG Success Criterion 1.1.1 Non-text Content for more information.

What should you write in your image description? As it turns out, writing great alt text is as much of an art form as it is a science. Essentially, you want to provide a text equivalent to whatever a sighted user gets out of the image. A lot of that depends on the context in which the image appears in the content.

One trick to help you get started is to imagine you're describing the image out loud to a friend.

What is the most important part of the image? Describe that first.
- For example: "Three dogs running on a grassy lawn."
What details would you draw their attention to so that they can recreate the image in their mind? Add those next. The details you choose may depend on the context provided by the text surrounding the image.
- Using the previous dog example: If the surrounding text is about how dog trainers should handle introducing a new dog to a play group, you might add, "The dogs have relaxed body posture. One dog is doing a play bow in front of the others."

A few other tips to get you started:

If there's text in the image, include that in the alt text. (Otherwise, non-sighted users won't have access to that information at all!)
For complex images like diagrams or charts, consider adding a text equivalent in the surrounding text. Then your alt text can be something like "A diagram"
Try to keep your descriptions short. Technically there's no character limit, but when screen readers are reading alt text, users don't have a way to pause or rewind the descriptions. If you have a long paragraph of description and a user misses something, they'll have to restart the alt text all the way from the beginning.

Learn more about how to write alt text: Web Accessibility Initiative: Alt Text Tips and Tricks

Tip #3: Use Descriptive Link Text

Frequently, when content writers add hyperlinks to their content, they'll write a sentence like "For more information, click here," and then add a hyperlink to the word "here." But this isn't accessible! According to WCAG Success Criterion 2.4.4 Link Purpose (In Context), linked text needs to have a descriptive name that indicates where the link will take the user.

Why is this important? Screen readers have a feature that lets users see a list of all the links on the current page. This list lets users quickly navigate to a particular link.

The links in the list are labeled by their link text. So if all the links in your content just say "here", then the screen reader links menu becomes essentially useless.

What can you do instead? Try using the title of the page you're linking to. (Want an example? Check out the links sprinkled throughout this post!)

Learn more about descriptive link text: Understanding Success Criterion 2.4.4 Link Purpose (In Context)

What Next?

Accessibility is important every day, but GAAD provides an opportunity to learn and discuss how we can create inclusive applications for all users.

Ready to learn more? Here are some resources to check out next:

Accessibility Fundamentals Overview: Beginner-friendly resources about how disabled people use technology and general accessibility principles.
WCAG 2 Overview: An introduction to the WCAG documents and how to use them.
The WebAIM Strategic Accessibility Framework: A set of indicators and benchmarks for how organizations and leadership can intentionally prioritize accessibility.

For developers:

MDN Web Docs on Accessibility: A technical introduction to accessible best practices for HTML, CSS, and JavaScript.
A11y Coffee: A collection of tips on accessibility quick wins and testing for developers.
A11ySupport.io: The caniuse of accessibility. Lists compatibility of various browser accessibility features for different screen reader and browser combinations.

How to Run a Sprint Retrospective

Megan Sullivan — Fri, 10 Feb 2023 05:22:23 +0000

Introduction

Businesses want teams to work together effectively so that they can produce value quickly. But it's not enough to just "always be shipping". Sometimes you need to take a beat, step back as a team, and reflect on your processes. "Go slow to go fast." That's where retrospectives come in.

A retrospective (or retro, for short) is a type of meeting where teammates reflect back on how they worked together over a period of time. Typically, retros are run at the end of an Agile sprint, usually every 2-4 weeks. In a retro, the team looks back on their accomplishments and brainstorms ways to make work more efficient and enjoyable in future sprints.

Sprint Retrospective at a glance:

Goal: To make process improvements by discussing what went well this sprint and what can be improved.

Duration: 1 hour

Frequency: Once per sprint (ideally every 2-3 weeks)

Participants: All individual contributors (ICs) & manager(s) on the team

Why do we need retros?

When you work on a team for a while, sometimes there's friction. Building software is hard, both from the technology side and the people side. There's a lot to balance—clashing personalities, different working preferences, team norms and expectations. But it's not always easy to bring up those issues when you're in the middle of the day-to-day grind. Sprint retrospectives provide a consistent safe space where teammates can bring up the challenges they're facing and find ways to work through them together.

Do we really need a retro at the end of every sprint?

Retros work best when you have them on a regular basis. That way, challenges can be addressed quickly, while there's still time for the team to pivot and make adjustments.

Think of it like navigation assistance when you're driving. You could wait until you're hopelessly lost before looking up directions to your final destination. But by that point, it's going to take a lot more effort to get you back on track. On the other hand, if you're using Google Maps from the get-go, you'll get notified as soon as you start heading in the wrong direction, and it'll be much easier to course correct.

In this post, I'll walk you through everything you need to know to facilitate your first sprint retrospective.

Before the meeting

To make sure everything runs smoothly on the day of your retro, it's important to prepare all the necessary pieces ahead of time.

Choose a retro framework to use

The retro framework you choose directly impacts the kinds of topics the team will discuss during the meeting.

Some popular options are:

Start, Stop, Continue: What should we to start, stop, and continue doing as a team?
Liked, Learned, Lacked: What did you like or learn this sprint? What was missing?
Anchors and Engines: What slows us down as a team? What helps us gain momentum?

Check out Fun Retrospectives for more example reflection frameworks.

How do you decide which framework to pick? If you get the sense that there's something the team wants or needs to talk about, you can find (or create!) categories that lead naturally to that kind of conversation. Otherwise, pick whichever framework strikes your fancy. (You can always mix it up and choose a different one for the next retro.)

Tip: If your team tends to feel nervous sharing constructive feedback, try renaming those categories to something like "Wished for" or "What could be improved?" (which sound a bit gentler than "Stop" or "Disliked").

Set up the retro board

Now that you know what retro framework you'll be using, it's time to set up a retro board to guide the conversation.

Personally, I prefer to use a virtual retro board instead of a physical whiteboard, even when I'm facilitating a retro in person. There's less cleanup, and the team gets to keep a digital record of the board that they can refer back to after the meeting. (But if analog is more your thing, that works too! Just make sure to gather enough sticky notes and pens for everyone participating.)

Platform options for building a virtual retro board:

(Ordered from least to most structured.)

FigJam: Super flexible, and feels the most like a whiteboard.

Trello: Kanban boards with columns, with optional add-ons for features like card voting.

EasyRetro: Kanban-style boards specifically for retros, with some built-in features like voting and sorting cards.

Parabol: Does much of the heavy lifting of facilitating for you. Applies a pre-defined structure to your retro agenda.

To set up your retro board:

Add a column for each of the categories from your retro framework.
Add additional columns for "Shoutouts" (where teammates can thank and celebrate each other) and "Action Items" (where you'll track next steps that come out of the retro conversation).
Include a link to the board in the calendar invite for your meeting.

Assign a notetaker for the retro

The last piece of prep is to assign someone to take notes during the retro. Ideally, this would be someone different from the facilitator (who will be focused on managing the conversation).

The notetaker's job is to make sure that all action items brought up in the meeting are added to the Action Items column on the board. They may also choose to write down additional context that comes up through the conversation.

To keep things fair and equally distribute the burden, I like to have a notetaker rotation. In the meeting invite, or at the top of each retro board, I'll write all the retro participants' names in alphabetical order. Then at the start of each retro, we check the list and see whose turn it is to take notes. (If you want to take things to the next level, you can also have a similar rotation for deciding who will facilitate the retro.)

During the meeting

It's game time! There are many ways to run a retro. Here's my preferred agenda:

Step 1: Set expectations (5 minutes)

As the facilitator, it's your job to set the tone for the meeting and create a space where folks feel comfortable sharing with the group.

I like to open retros by doing the following:

Remind everyone of the Agile Prime Directive: "Regardless of what we discover, we understand and truly believe that everyone did the best job they could, given what they knew at the time, their skills and abilities, the resources available, and the situation at hand."
- Why? Retros are not about placing blame for things that did or didn't happen this sprint. Instead, they're about looking for opportunities to learn and improve in the future.
Take a quick pulse check. In the chat, each participant writes a number from 1-5, rating how they're feeling going into this conversation. (Where 5 means "I'm open to talking about anything," and 1 means "I'm more comfortable listening/observing".)
- Why? We're all human. Sometimes, there are other things going on in our lives, and we're not in the mood to have a potentially squishy conversation about teamwork. As a facilitator, it's good to know what energy the group is starting with. If many folks are feeling more reserved, it might be a good idea to reschedule the retro for a time when folks are more open to sharing and discussing.
Review the action items from the previous retro. Follow up on what's been done and what still needs to be carried over. (The notetaker copies over any remaining action items to the Action Items section of the new retro board.)
- Why? Knowing that action items will actually be followed up on helps keep folks accountable for what the said they'd get done. Or it helps to remind folks of tasks they might have forgotten about in the shuffle of day-to-day work.

Step 2: Brain dump (10 minutes)

Now that everyone is in the right headspace, it's time for folks to add all their ideas to the retro board!

Set a timer for 7 minutes. Silently, each teammate simultaneously adds their thoughts to each topic on the retro board. Teammates write each thought on a separate card or sticky note. They can write as many cards as it takes to cover everything that's on their mind.
When the timer goes off (or when everyone's done writing), take another 2-3 minutes as a group to read over the cards silently, and group them into related topics. Draw boundaries around the related cards, and add a concise label to summarize the topic (like "too many meetings" or "unclear team priorities").

Note: Retrospectives are about process, not progress. When identifying areas for improvement, focus more on how you're working together, as opposed to what work still needs to be done. (There are other types of meetings for those tactical progress conversations, like sprint planning and standups.)

For example, let's say the team didn't finish all the tickets assigned for the sprint. Instead of writing a card like, "We still need to do tickets X, Y, and Z," encourage teammates to dig deeper and think about what may have gotten in the way of completing that work. For example, "We added new tickets to the sprint halfway through the week, which meant our workload estimations were off."

Step 3: Vote (1 minute)

Once all participants have had a chance to read the cards to themselves, it's time to vote on which topics to discuss as a group. This gives everyone a chance to show support for their teammates' perspectives, which helps folks feel validated while also identifying broader patterns in team sentiments.

Each teammate gets a total of 5 votes, which they distribute among the different topics. (You're allowed to vote for the same topic multiple times.)
Once all the votes have been tallied, you'll have a prioritized list of topics to discuss in the next step.

Note: The goal of the voting exercise is to rank which topics the team wants to talk about as a group. This means that some cards or topics (with the least votes) won't be verbally addressed during the meeting. But that's okay, because everyone had a chance to read them all in the previous step.

Step 4: Discuss (30 minutes)

You've got a list of ranked topics. Now it's time to dig into the discussion! (This is the meat and potatoes of your retro.)

As a group, discuss each topic on the board. Start with the one with the most votes, and work your way down from there. For each topic:

To kick off the conversation, restate the topic (or read the card aloud) and then ask the group, "Does anyone want to share some more context on that?" Often, the person who wrote the card may speak up to add some more detail, or another teammate may be inspired to share their experience.
Guide the conversation by asking follow-up questions like, "What do you mean by [something they said]?" or "Can you share an example?" or even just "Will you say more about that?" If the discussion starts to drift to another topic, refocus the group by saying something like, "Before we get to that, was there anything else anyone wanted to add about [the previous topic]?"
Once the group has a shared understanding of the current topic, shift the discussion to action items. You can say something like, "What action items could we take that would help address [the topic]?" The notetaker tracks action items as they're identified and adds them to the Action Items section of the board.

Typically, you'll have more topics than you can cover in the allotted amount of time, but that's okay. If those undiscussed topics are still important, odds are they'll show up again in a future retro.

Facilitation tips:

Leading group discussions is hard! Here are some suggestions for how to handle common pitfalls:

Ask, don't tell. Avoid the temptation to read out the cards and then add your own perspective on what it's referring to. You may be missing context or misinterpreting the author's original intention. Instead, ask follow-up questions and let teammates share what they mean in their own words.

Sit with the silence. Often, new facilitators will ask a question, and if no one instantly responds they'll move on to the next topic. But it takes participants time to hear the question, think of a response, decide how to word their response, find the unmute button, etc. Seasoned educators typically recommend leaving 5 seconds of wait time after asking a question, to give learners an opportunity to answer. (It may feel awkward at first, but I promise the silence feels longer to you than it does to everyone else!)

Use timers! Does your group tend to spend too long on a single topic? Set a 3-minute timer when you start discussing a new topic. When the timer goes off, have a quick show of hands to see who wants to continue discussing this topic and who wants to move on. (Again, it may feel awkward interrupting the conversation at first, but after a few rounds folks will get used to the rhythm.)

Step 5: Close out the meeting (5 minutes)

By this point, you've discussed the topics that were most important to the team, and the group has identified a list of action items to follow up on after the meeting.

Now it's time to wrap things up:

Review the tasks in the Action Items column, and make sure each one is assigned to an individual owner.
- The assigned owner doesn't necessarily have to be the one who will actually complete the task. But they're the one responsible for following up on it and making sure the team doesn't forget about it.
If you have a facilitator rotation, assign the facilitator (and notetaker) for the next retro, so that they know to start preparing.
(Optional) I like to end things on a high note by sharing "warm fuzzies". Each teammate takes a moment to share a shoutout with someone else on the team. If everyone is comfortable with it, share these shoutouts in a public team channel so that others have visibility into their awesome work! Or if they'd prefer private praise, send it to them in a direct message.

After the meeting

Shortly after the retro, send a Slack or email summary of the action items and their assigned owners, so that teammates can keep them top-of-mind.

And that's all there is to it! Congratulations on facilitating your first sprint retrospective!

Wrap it up

Sprint retrospectives are my favorite kind of meeting. They're a chance to reflect back on your work as a team and celebrate your accomplishments. A chance to talk about challenging experiences and find ways to ease that friction in the future. A chance to connect with teammates and say, "This was how I felt over the last few weeks. Did you feel that too?"

Sometimes they can lead to tough conversations. But if you can create a safe space where your team feels comfortable opening up and being vulnerable, it can lead to transformational changes.

Resources

Example retro board in FigJam: Take a closer look at the sample retro board from this post. (In your own retros, you won't need multiple copies of your board in the same file.)
Fun Retrospectives: List of several different retro frameworks you can use to structure your retro board. Includes different formats for different kinds of reflections. Choose whatever one fits the kind of conversation you think your team needs to have.
Agile Retrospective Resource Wiki: A collection of sample agendas and tips for running retros.
How to run a great retrospective: LeadDev Blog post by Nickolas Means.
Team Meetings That Don't Suck - Avoid Retrospectives Antipatterns: GOTO Conference talk by Aino Vonge Corry, author of Retrospectives Antipatterns.

How to run a 360 Speedback

Megan Sullivan — Wed, 23 Nov 2022 01:04:16 +0000

Introduction

We all need feedback to help us grow. As Sarah Drasner says in her book, Engineering Management for the Rest of Us, "We can steer our own ship to some extent, but at some point we can't always see our own work clearly, and we need input from others to improve."

A 360˚ speedback is a type of meeting used for quickly sharing 1:1 feedback with teammates. (It's kind of like speed dating, but for exchanging feedback!) By the end of the speedback, everyone on the team will have shared feedback with everyone else.

In this post, you'll learn how to prepare for and facilitate your first speedback.

How it works

Before the meeting:

Teammates share their individual goals for what they want feedback on.
- This can be anything that the individual finds helpful: a behavior they're trying to improve, leadership skills they're developing, content areas they're trying to build expertise in, etc.
- Store these goals in a shared document or spreadsheet. Using a spreadsheet is a handy way to track how goals change over time. Label each row with a teammate's name, and label each column with the date of the speedback session. In each cell, teammates can put the goals they're looking for feedback on for that speedback session. (Check out the example below.)

Teammate	November 17, 2022	October 6, 2022
Megan	Meeting facilitation. Do our meetings feel efficient? What could I improve about the way I facilitate?	...
Tahia	Code reviews. Am I leaving a good balance of positive and constructive comments?	...
Angelo	Communication. Are my standup updates clear and easy to understand? What kind of information is most helpful in these updates?	...

Tip: Prepare this list of goals as far in advance as possible. That way, teammates have time to keep an eye out for concrete examples of specific behaviors, which they can reference to give more meaningful feedback.

The speedback facilitator creates the list of pair rotations for each round. (See the appendix below on creating pair rotations.)
The speedback facilitator creates the meeting invite.
- The total meeting duration should be 7 minutes times the number of pair rotations. (So if your team has 5 rounds of pair rotations, the meeting should be 35 minutes long.)

During the meeting:

Complete as many rounds as it takes to get through all the pair rotations.

Note: Speedbacks can be run remotely or in person! This post assumes you're running a remote speedback.

If you're facilitating an in-person speedback, the process looks mostly the same. But instead of using Zoom breakout rooms, you'll need to designate separate quiet areas where each pair can speak in private.

For each round:

(1 minute) The facilitator sets up separate Zoom breakout rooms for each pair, and everyone joins their assigned breakout room. (If you're doing an in-person speedback, this time can be used for physically moving to the location for your next pairing.)
- Each breakout room contains a single pair of teammates, Person A and Person B.
- Have an odd number of participants? One person will be alone each round. I like to have this person look up a quick joke or fun fact to share when the group comes back together at the end of the round, while the facilitator assigns the next set of breakout rooms.
(3 minutes) In each breakout room, one person sets a timer for 3 minutes. Then Person A gives Person B feedback. Person B listens and takes notes. Person B can ask follow-up questions if needed, but Person A should be doing most of the talking.
- This feedback can be related to what Person B put in their goals, or it can be something else Person A thinks would be helpful to hear. (Praise, areas for growth, progress on feedback topics from the previous speedback, etc.)
(3 minutes) When the first timer goes off, each pair switches roles and sets another timer for 3 minutes. Now Person B gives Person A feedback. Similarly, Person B should be doing most of the talking, while Person A listens.
When the second timer goes off, all the pairs rejoin the main Zoom room and wait for the next round.

Not sure what to say?

Here are some resources with tips on how to give and receive feedback gracefully:

How to get feedback without falling apart, by Liz Fosslien. Tips on receiving feedback.

How to give feedback that doesn't pack a painful punch, by Liz Fosslien. Tips on giving constructive feedback.

Once the group makes it through all the pair rotations, you're done! 🥳

After the meeting:

The facilitator schedules the next speedback! (I've found that having one speedback every 4-6 weeks is a good cadence. It's frequent enough to check in regularly, and spaced out enough to leave time to make meaningful progress.)
Teammates update their individual goals in the shared doc. They can choose to keep working on the same goal, or they can switch it up and pick a different thing they'd like feedback on.

Wrap it up

Speedbacks are a great time to celebrate your teammates and the hard work you all do. They also help us recognize where we still have room to grow and improve.

Giving and receiving feedback might feel scary at first. But the more you practice having these conversations, the easier they'll get. Hang in there!

A closing caveat

This one goes out to all you people-pleasers out there.

It's important to remember that feedback is a gift. But ultimately, you get to decide whether or not to act on a specific piece of feedback.

If something feels off about a suggestion, you don't have to address it. It's okay to note it as a single data point, and move on. That said, if you hear the same suggestion from multiple teammates, it may be a sign that there's something worth reevaluating.

Appendix: Creating pair rotations

These instructions will help the facilitator create the list of pair rotations for the speedback.

If you have an odd number of participants:

For the first round, write everyone's names in two rows. Each column represents a pair who will be matched up for that round. There should be one empty space left in one of the rooms.
For the next round, rotate each person's name one position clockwise around the circle. Make sure to skip over the empty space, so that the empty space stays in the same position from the first round.
Continue rotating everyone around the circle for each round, until everyone makes it back to the position where they started.

Here's an example for a group of 5 participants (named A, B, C, D, and E):

Expand for detailed image description

There are five rows, one for each round of the speedback. There are also three columns, one for each breakout room.

In round 1:

Room 1 has only Person A.
Room 2 has Person B and Person E.
Room 3 has person C and Person D.

Then all the names rotate one position clockwise. In round 2:

Room 1 has only Person E.
Room 2 has Person A and Person D.
Room 3 has Person B and Person C.

Again, all the names rotate one position clockwise. In round 3:

Room 1 has only Person D.
Room 2 has Person E and Person C.
Room 3 has Person A and Person B.

Again, all the names rotate one position clockwise. In round 4:

Room 1 has only Person C.
Room 2 has Person D and Person B.
Room 3 has Person E and Person A.

Once more, all the names rotate one position clockwise. In round 5:

Room 1 has only Person B.
Room 2 has Person C and Person A.
Room 3 has Person D and Person E.

If you have an even number of participants:

The process for assigning pairs is similar, with one difference: After step 1, choose one person to stay in the same position for every round. Then rotate everyone else using the same process as before.

Here's an example with 4 participants (named A, B, C, and D):

Expand for detailed image description

With an even number of teammates, pick one person to stay in the same place every round, and rotate everyone else. (In this example, Person A stays in the same position every round.)

There are three rows, one for each round of the speedback. There are also two columns, one for each breakout room.

In round 1:

Room 1 has Person A and Person D.
Room 2 has Person B and Person C.

Then all the names (except Person A) rotate one position clockwise. In round 2:

Room 1 has Person A and Person C.
Room 2 has Person D and Person B.

Once more, all the names (except Person A) rotate one position clockwise. In round 3:

Room 1 has Person A and Person B.
Room 2 has Person C and Person D.

Switching between zsh Themes with a Shell Command

Megan Sullivan — Thu, 07 Jul 2022 07:04:42 +0000

Introduction

When you're recording a screencast for your latest piece of educational content, it's a good idea to simplify your dev setup. Removing distracting tooling customizations reduces cognitive load, so that learners can focus on the key ideas you want them to understand.

But as a developer, you probably also have your own preferences for tooling when you're working on your own programming projects outside of teaching.

There's a great post by Joe Previte on How to Create Code Profiles in VSCode, which shows you how to create a shell command that switches between two different sets of VS Code settings.

In this post, we'll expand that shell command to also switch between command prompt themes, to keep your terminal simple and distraction-free.

Prerequisites

This post assumes that:

You're using zsh.
- Not sure which shell you're using? On a Mac, open the Terminal app, and run echo $SHELL. It should output /bin/zsh.
- Note: If you're using bash, you can still use the same principles from this post. But anywhere it says zshrc, you'll use bashrc instead.
You have Oh My Zsh installed. This is what we'll use for customizing zsh themes.
You've set up VS Code to allow launching from the command line.
You've followed Joe's post on How to Create Code Profiles in VSCode.
- TL;DR: Create a new file at ~/code_profiles/teaching/data/User/settings.json. Paste your VS Code settings for screencasts in there.

Not sure what settings to use for screencasts?

Here are the settings we use at Apollo for recording screencasts for the Odyssey learning platform.

{  
  "zenMode.hideLineNumbers": false,  
  "workbench.colorTheme": "Apollo Midnight",  
  "editor.quickSuggestions": {  
    "other": false,  
    "comments": false,  
    "strings": false  
  },  
  "editor.wordBasedSuggestions": false,  
  "editor.suggestOnTriggerCharacters": false,  
  "workbench.statusBar.visible": false,  
  "editor.renderLineHighlight": "none",  
  "javascript.updateImportsOnFileMove.enabled": "always",  
  "editor.minimap.enabled": false,  
  "git.enableSmartCommit": false,  
  "window.zoomLevel": 3,  
  "zenMode.centerLayout": false,  
  "zenMode.fullScreen": false,  
  "editor.suggest.snippetsPreventQuickSuggestions": false,  
  "html.suggest.html5": false,  
  "editor.parameterHints.enabled": false,  
  "workbench.tips.enabled": false,  
  "editor.lightbulb.enabled": false,  
  "editor.hover.sticky": false,  
  "npm.fetchOnlinePackageInfo": false,  
  "editor.hover.enabled": false,  
  "editor.formatOnSave": true,  
  "editor.fontSize": 19,  
  "git.enabled": false, // prevents color-coding file names in the Explorer sidebar based on Git status
  "prettier.printWidth": 80,  
  "editor.glyphMargin": false,  
  "editor.cursorBlinking": "solid",  
  "editor.defaultFormatter": "esbenp.prettier-vscode",  
  "[javascript]": {  
    "editor.defaultFormatter": "esbenp.prettier-vscode"  
  },  
  "prettier.enable": true,  
  "eslint.format.enable": false,  
  "workbench.fontAliasing": "default",  
  "workbench.activityBar.visible": false  
}

What you will build

Joe's post sets up a teach alias, which you can run from the command line. This command opens a folder in a new VS Code window, with your screencasting settings loaded.

In this post, we'll expand the teach command to understand a few different options. Here's the API we'll build:

teach screencast <folder>
1. Opens the specified folder in VS Code using your screencasting settings.
2. Switches shell preference to your screencasting zsh theme.
teach reset
1. Sets shell preference back to your personal zsh theme.
2. The next time you run code <file> from the command line, it will load VS code with your original personal settings.

The architecture

To build the teach command, we'll be configuring our ~/.zshrc file. The ~/.zshrc file gets run automatically whenever a new terminal window is open. (The "rc" stands for "run commands".)

Here's a high-level overview of the architecture we'll build to load the correct shell theme:

Whenever a new terminal window is opened, the ~/.zshrc file runs.
We'll set up our ~/.zshrc file to source another file called ~/zshrc/teach.sh.
The ~/zshrc/teach.sh script will check the contents of a text file called ~/zshrc/CURRENT_PROMPT_THEME.
Use the contents of CURRENT_PROMPT_THEME to load the correct zsh theme.
- If the file's contents are the string "screencast", then ~/zshrc/teach.sh will source the zsh theme from the ~/zshrc/screencast-zsh-theme.sh file.
- Otherwise, if the file's contents are the string "personal", then ~/zshrc/teach.sh will source the zsh theme from ~/zshrc/personal-zsh-theme.sh.

Note: You could (in the way that all things are possible) just put all this logic directly into your ~/.zshrc file. But we're going to break it up into multiple files, to keep things modular and tidy.

Instructions

Let's get to it!

1) Create a new file called ~/zshrc/personal-zsh-theme.sh. You can do this from the command line by running the following:

mkdir ~/zshrc
touch ~/zshrc/personal-zsh-theme.sh

2) Move your existing personal zsh theme settings out of ~/.zshrc and into the ~/zshrc/personal-prompt.sh file. Here's what mine looks like:

# Path to your oh-my-zsh installation.
export ZSH="/Users/megansullivan/.oh-my-zsh"

# Set name of the theme to load --- if set to "random", it will
# load a random theme each time oh-my-zsh is loaded, in which case,
# to know which specific one was loaded, run: echo $RANDOM_THEME
# See https://github.com/ohmyzsh/ohmyzsh/wiki/Themes
ZSH_THEME="robbyrussell"

# Which plugins would you like to load?
# Standard plugins can be found in $ZSH/plugins/
# Custom plugins may be added to $ZSH_CUSTOM/plugins/
# Example format: plugins=(rails git textmate ruby lighthouse)
# Add wisely, as too many plugins slow down shell startup.
plugins=(git)

source $ZSH/oh-my-zsh.sh

3) Create a new file, ~/zshrc/screencast-zsh-theme.sh. You can do this from the command line by running the following command:

touch ~/zshrc/screencast-zsh-theme.sh

4) Put your zsh theme settings for screencasting in the new ~/zshrc/screencast-zsh-theme.sh file. At Apollo we use the powerlevel10k theme for screencasts, so here's what my teach theme looks like:

# Enable Powerlevel10k instant prompt. Should stay close to the top of ~/.zshrc.
# Initialization code that may require console input (password prompts, [y/n]
# confirmations, etc.) must go above this block; everything else may go below.
if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then
  source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh"
fi

# Path to your oh-my-zsh installation.
export ZSH="/Users/megansullivan/.oh-my-zsh"

# Set name of the theme to load --- if set to "random", it will
# load a random theme each time oh-my-zsh is loaded, in which case,
# to know which specific one was loaded, run: echo $RANDOM_THEME
# See https://github.com/ohmyzsh/ohmyzsh/wiki/Themes
ZSH_THEME="powerlevel10k/powerlevel10k"

# Which plugins would you like to load?
# Standard plugins can be found in $ZSH/plugins/
# Custom plugins may be added to $ZSH_CUSTOM/plugins/
# Example format: plugins=(rails git textmate ruby lighthouse)
# Add wisely, as too many plugins slow down shell startup.
plugins=(git)

source $ZSH/oh-my-zsh.sh

# To customize prompt, run `p10k configure` or edit ~/.p10k.zsh.
[[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh

Note: Using powerlevel10k requires some extra installation steps, which you'll need to do first. For more details, refer to the powerlevel10k installation instructions for Oh My Zsh.

5) Set the initial value of the ~/zshrc/CURRENT_PROMPT_THEME file to "personal" by running the following from the command line:

echo "personal" > ~/zshrc/CURRENT_PROMPT_THEME

6) Create a new file, ~/zshrc/teach.sh. You can do this from the command line by running the following:

touch ~/zshrc/teach.sh

7) Add the following to ~/zshrc/teach.sh:

# read the CURRENT_PROMPT_THEME file, and load the corresponding shell theme
cat ~/zshrc/CURRENT_PROMPT_THEME | while read line; do
  if [[ $line = "personal" ]]
  then
    source ~/zshrc/personal-zsh-theme.sh;
  elif [[ $line = "screencast" ]]
  then
    source ~/zshrc/screencast-zsh-theme.sh;
  fi
done

# defines a "teach" command that can be run from the command line
teach() {
  # usage: teach reset
  # - sets shell preference back to personal theme
  if [[ $1 = "reset" ]]
  then 
    source ~/zshrc/personal-zsh-theme.sh;
    echo "personal" > ~/zshrc/CURRENT_PROMPT_THEME;

  # usage: teach screencast <folder>
  # - switches shell preference to screencast theme
  # - opens the specified folder in VS Code using screencast settings
  elif [[ $1 = "screencast" ]]
  then
    source ~/zshrc/screencast-zsh-theme.sh;
    echo "screencast" > ~/zshrc/CURRENT_PROMPT_THEME
    code --user-data-dir ~/code_profiles/teaching/data $2;

  # default message
  else
    echo "  Command not recognized. Options:";
    echo "  - teach reset: restore personal preferences for command prompt";
    echo "  - teach screencast <folder>: switch command prompt and open with VS code settings for screencasting";
  fi
}

8) Add the following line somewhere in your ~/.zshrc file (the exact position doesn't matter):

source ~/zshrc/teach.sh

9) Manually reload your ~/.zshrc file by running the following from the command line:

source ~/.zshrc

Now you should be able to use the teach command! Let's test it out in the next section.

Testing it out

Time to see our shell script in action! Let's test out the teach command and make sure it behaves correctly.

Switching to screencasting settings

First, let's check that our screencasting settings load correctly. Run the following from the command line:

teach screencast ~

This should open your home directory in a new VS Code window, using your screencast VS Code settings.

Open the VS Code integrated terminal. It should be using your screencasting zsh theme.

Switching to personal settings

Now, let's check that we can reset to our personal settings correctly. Run the following from the command line:

teach reset

Now when you open a new shell window (in Terminal or in VS Code), it should be using your personal zsh theme.

🚨 Known issue: On my machine, after running teach reset, the shell theme in my existing terminal window doesn't update. But if I open a new window/tab, it will load the correct zsh theme.

This happens because the p10k theme I use for my teaching zsh theme sets a bunch of environment variables that don't get unset in the current shell when teach reset gets run. So some combination of those p10k environment variables gets in the way of zsh using my personal theme. Opening a new shell window works because then the ~/.zshrc file starts fresh and only loads the environment variables for my personal theme.

This isn't a huge deal for me, since I won't be switching themes in the middle of a screencast, and it's a minor chore to open up a new terminal window. But if you can think of an easy way to fix it, let me know!

Wrap it up

You did it! Now you can use the teach command to switch between shell themes.

I hope this post was helpful. If you enjoyed it, reach out on Twitter or leave a tip via Ko-fi. I can't wait to see the cool things you create!

#DevEdBookClub Round 3: Teaching Tech Together

Megan Sullivan — Mon, 13 Jun 2022 20:46:00 +0000

It's time for our next round of our Twitter book club, and you're invited! Each week, we'll host a Twitter chat on Thursday at 6pm PT to discuss a chapter of Teaching Tech Together: How to create and deliver lessons that work and build a teaching community around them. We start with Chapter 1 on July 7.

Why join? Because learning is more fun together!

How to Participate

If you want to read along with us, here's what you need to do:

Teaching Tech Together can be read online for free! If you'd like to support the author by ordering a physical copy, you can purchase one from the publisher website.
Before the day of the Twitter chat, read the assigned chapter for the week. Jot down any quotes that stand out to you or questions you have.
On the day of the Twitter chat, hop onto Twitter between 6pm-7pm PT. Check the @DevEdBookClub Twitter account for the discussion thread.
Join the conversation (and tag your replies with #DevEdBookClub)! Check out what other participants are saying. Reply with your own thoughts, experiences, or questions. This is a great time to learn from each other and make new friends!

If you can't attend during the scheduled time, you can still add to the conversation after the fact. We'd love to hear your thoughts, whenever you have time to share them! We'll also update this post with links to each thread, so you can easily catch up on all the conversations in one place.

Schedule

Like to plan ahead? Here's when we're currently planning to discuss each chapter.

Note: We're trying something a little different this time. There will be no book club chat on the last Thursday of each month. We're hoping these periodic breaks will give folks a chance to catch up on the reading and to jump back into the conversation. Let us know what you think of this new structure!

July 7, 2022: Chapter 1 (Introduction)
July 14: Chapter 2 (Mental Models and Formative Assessment)
July 21: Chapter 3 (Expertise and Memory)
July 28: No book club! Relax or catch up on reading 😎
August 4: Chapter 4 (Cognitive Architecture)
August 11: Chapter 5 (Individual Learning)
August 18: Chapter 6 (A Lesson Design Process)
August 25: No book club! Relax or catch up on reading 😎
September 1: Chapter 7 (Pedagogical Content Knowledge)
September 8: Chapter 8 (Teaching as a Performance Art)
September 15: Chapter 9 (In the Classroom)
September 22: Chapter 10 (Motivation and Demotivation)
September 29: No book club! Relax or catch up on reading 😎
October 6: Chapter 11 (Teaching Online)
October 13: Chapter 12 (Exercise Types)
October 20: Chapter 13 (Building a Community of Practice)
October 27: No book club! Relax or catch up on reading 😎
November 3: Chapter 14 (Outreach)
November 10: Chapter 15 (Why I Teach)
November 17: General Wrap-Up / Final Thoughts

Have questions?

Leave a comment below, or reach out to us on Twitter!

See you on July 7!

My Reading List for Developer Educators

Megan Sullivan — Mon, 23 May 2022 21:42:24 +0000

Introduction

One of the best ways to deeply learn a subject is by teaching it to others. But being a good teacher is about more than just brain-dumping everything you know about a topic. How can you make sure you're teaching in a way that's actually helping people learn?

I've read a lot about learning and education since I started teaching in 2014. Here's a list of my favorite resources on how to become a better educator.

My #1 recommendation

Teaching Tech Together: How to create lessons that work and build a teaching community around them, by Greg Wilson

If you only read one book from this list, let it be this one. The whole time I was reading it, I constantly nodded my head emphatically at each new point.

Teaching Tech Together covers education best practices touched on by other resources in this list, but what sets it apart is its specific focus on people who are teaching programming. It's perfect for anyone looking for a crash course in pedagogy within the context of engineering. The book is extremely well researched, and it's jam-packed with interesting concepts and practical techniques.

Quote from the publisher's website:

Hundreds of grassroots groups have sprung up around the world to teach programming, web design, robotics, and other skills outside traditional classrooms. These groups exist so that people don't have to learn these things on their own, but ironically, their founders and instructors are often teaching themselves how to teach.

There's a better way. This book presents evidence-based practices that will help you create and deliver lessons that work and build a teaching community around them. Topics include the differences between different kinds of learners, diagnosing and correcting misunderstandings, teaching as a performance art, what motivates and demotivates adult learners, how to be a good ally, fostering a healthy community, getting the word out, and building alliances with like-minded groups. The book includes over a hundred exercises that can be done individually or in groups, over 350 references, and a glossary to help you navigate educational jargon.

Resources on how people learn

Learning How to Learn, by Barbara Oakley

This Coursera course covers cognitive-science research on how your brain works, and how you can optimize your learning strategies to retain information more effectively. The videos are short and sweet, with plenty of analogies to make the content relatable.

Quote from the Coursera course page:

This course gives you easy access to the invaluable learning techniques used by experts in art, music, literature, math, science, sports, and many other disciplines. We'll learn about how the brain uses two very different learning modes and how it encapsulates (“chunks”) information. We'll also cover illusions of learning, memory techniques, dealing with procrastination, and best practices shown by research to be most effective in helping you master tough subjects.

Using these approaches, no matter what your skill levels in topics you would like to master, you can change your thinking and change your life.

Make It Stick, by Peter C. Brown, Henry L. Roediger III, and Mark A. McDaniel

This book is a great introduction to learning science and how your memory works.

Make It Stick covers similar material to Learning How to Learn, interwoven with stories and examples from cognitive-science research. The tone is conversational and easy to read, and each chapter ends with a handy "Takeaway" section that reiterates the key ideas.

Quote from the publisher's website:

Many common study habits and practice routines turn out to be counterproductive. Underlining and highlighting, rereading, cramming, and single-minded repetition of new skills create the illusion of mastery, but gains fade quickly. More complex and durable learning come from self-testing, introducing certain difficulties in practice, waiting to re-study new material until a little forgetting has set in, and interleaving the practice of one skill or topic with another. Speaking most urgently to students, teachers, trainers, and athletes, Make It Stick will appeal to all those interested in the challenge of lifelong learning and self-improvement.

Practice Perfect, by Doug Lemov, Erica Woolway, and Katie Yezzi

This book refutes the old saying that "practice makes perfect," and instead argues that "practice makes permanent." In other words, the way that you practice will be the way that you perform, so make sure you practice doing it right.

Practice Perfect includes 42 techniques for how to practice skills effectively. It includes examples from a wide variety of industries, including sports, music, and medicine. This book changed the way I think about facilitating workshops and my stance on rote memorization.

Quote from the publisher's website:

By researching the latest in brain and behavioral science and in their work training teachers with Uncommon Schools, the authors found that what you do in practice matters as much if not more than how much you practice. There is a right way and a wrong way to practice. The right way involves breaking through assumptions, modeling excellent practice, using feedback, creating a culture of practice, making new skills stick, and hiring for practice.

Resources on designing educational content

Understanding by Design, by Grant Wiggins and Jay McTighe

This book is the go-to resource on backward design, a framework for planning and writing curricula. It's the approach I always use when I'm working on a new course.

Instead of the conventional approach of starting a lesson plan with an outline of the activities you want students to complete, backward design flips things around and starts with learning objectives first. What do you want students to be able to do after this lesson? What assessments will help you measure whether or not they're able to do those things? Only after answering those questions do you start thinking about the activities that will help students complete those assessments and achieve the desired learning objectives.

The authors also created an Understanding by Design Professional Development Workbook, which has lots of examples of putting the framework into practice. It also includes several worksheets that you can use to apply the process to your own courses.

Quote from the introduction:

As the title suggests, this book is about good design—of curriculum, assessment, and instruction—focused on developing and deepening understanding of important ideas. Posed as a question, considered throughout the book and from many perspectives, the essence of this book is this: How do we make it more likely—by our design—that more students really understand what they are asked to learn? So often, by contrast, those who "get it" are learners who come to us already able and articulate—understanding by good fortune. What must our planning entail to have an intellectual impact on everyone: the less experienced; the highly able, but unmotivated; the less able; those with varied interests and styles?

Head First series created by Kathy Sierra and Bert Bates

This one isn't explicitly about teaching readers how to be better teachers. But it's a masterclass on how to make technical content engaging and "sticky" so that it's easier for learners to digest and retain.

One of the hallmarks of the Head First series is the writing style. At first glance, the quirky comics, diagrams, and character dialogue might seem like a gimmick. But the introduction of each book explains how their writing style is based in cognitive-science research. It's intentionally designed to transform potentially dull technical topics into something fun that your brain actually wants to pay attention to.

The series has books on a wide variety of technical topics, from web dev to Git to design patterns, so you're sure to find something you're interested in.

Quote from the introduction of the 2nd edition of Head First Java:

We've all had the "I really want to learn this but I can't stay awake past page one" experience. Your brain pays attention to things that are out of the ordinary, interesting, strange, eye-catching, unexpected. Learning a new, tough, technical topic doesn't have to be boring. Your brain will learn much more quickly if it's not.

Docs for Developers: An Engineer's Field Guide to Technical Writing, by Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, and Heidi Waterhouse

This one is for all you technical writers out there!

Docs for Developers walks readers through the process of building a user-centered documentation site—from planning to writing to maintaining, and everything in between. It includes several helpful lists of guiding questions, making it the perfect reference book for any documentarian's desk.

The book also includes a narrative throughline about a fictional tech company called Corgi.ly. Each chapter checks in on the developers at Corgi.ly as they build out the documentation site for their dog-bark-translator API. The narrative helps set up the context for the chapter and relates the theory back to a real-world scenario. (And it means we get cute corgi illustrations!)

Note: A group of us read Docs for Developers with Dev Ed Book Club. We had weekly Twitter chats to discuss each chapter. You can check out the archive of our past discussions in our DEV post about Dev Ed Book Club: Docs for Developers.

Quote from the introduction:

We created this field guide to technical documentation by building on our own expertise and feedback from a multitude of developers. It's designed as a resource to keep at hand, so you can write documentation as part of your software development process.

This book walks you through creating documentation from scratch. It begins with identifying the needs of your users and creating a plan with common patterns of documentation, then moves through the process of drafting, editing, and publishing your content. The book concludes with practical advice about integrating feedback, measuring effectiveness, and maintaining your documentation as it grows.

Resources on classroom management

Lost at School, by Ross W. Greene

This is a book about how to work with students who often get labeled as "challenging." The central theme of this book is "kids do well if they can," a principle in direct opposition to what many believe (that "kids do well if they want to"). The author introduces a model called Collaborative Problem Solving (CPS), a behavior management strategy that stems from meeting students where they are and working together to find solutions to disruptive behaviors.

Like Docs for Developers, this book includes a narrative throughline showing how to use CPS in practice, so readers can see how the ideas from each chapter build on each other and develop the confidence to use the framework on their own.

Lost at School is geared toward teachers working in public schools, but honestly it's also a good read for managers, parents, or anyone who needs help figuring out how to give constructive feedback. If you'd prefer a video, here's a YouTube playlist of Dr. Ross Greene explaining Collaborative Problem Solving.

Quote from the introduction:

Helping kids with social, emotional, and behavioral challenges is not a mechanical exercise. Kids aren't robots, adults aren't robots, and helping them work together isn't robotic. The work is hard, messy, uncomfortable, and requires teamwork, patience, and tenacity, especially as the work also involves questioning conventional wisdom and practice. This book contains lots of material and examples to help you better understand challenging kids, how to implement the [Collaborative Problem Solving] model, and how to work collaboratively toward the common goal of helping these kids more effectively.

Teach Like a Champion, by Doug Lemov

This book contains 62 practical techniques on everything from engaging students in group discussions to building a classroom culture that normalizes and celebrates error. Each technique is explained with concrete examples, making it easy to incorporate into your next lesson.

It's aimed at teachers working to close the achievement gap in K-12 schools, but the techniques can also be used by anyone who facilitates live workshops.

Quote from the book's website:

Upon studying videos of high-performing teachers, Lemov distills their methods into concrete tangible actions for others to use and adapt...

Through the techniques, Lemov explains how to Check for Understanding, raise academic expectations, increase the ratio of the cognitive work students do, motivate and engage students, make classrooms more writing-intensive, improve discussions, and anticipate when it is necessary to redirect student behavior so it is positive and productive.

Wrap it up!

For easy reference, here's a quick list of all the resources from this post:

My #1 recommendation
- Teaching Tech Together: How to create lessons that work and build a teaching community around them, by Greg Wilson
Resources on how people learn
- Learning How to Learn, by Barbara Oakley
- Make It Stick, by Peter C. Brown, Henry L. Roediger III, and Mark A. McDaniel
- Practice Perfect, by Doug Lemov, Erica Woolway, and Katie Yezzi
Resources on designing educational content
- Understanding by Design, by Grant Wiggins and Jay McTighe
- Head First series created by Kathy Sierra and Bert Bates
- Docs for Developers: An Engineer's Field Guide to Technical Writing, by Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, and Heidi Waterhouse
Resources on classroom management
- Lost at School, by Ross W. Greene
- Teach Like a Champion, by Doug Lemov

I'm always looking to learn more about how to be a good teacher! What are some of your favorite resources on education?

Docs for Everyone!

Megan Sullivan — Wed, 18 May 2022 07:14:57 +0000

Note: This article is adapted from a talk I gave at GatsbyCamp Fall 2021, which you can watch below.

In my life before being a developer, I was a teacher and curriculum writer. And one of the best feelings as an educator was helping learners who felt confused or overwhelmed gain confidence in their abilities to create cool things.

Similarly, one of things I love about documentation is that it lets you have that same impact of helping people deepen their skills. But with documentation, you have that impact at a much larger scale than is possible through 1:1 interactions.

Want numbers? Last March, I taught an Intro to Gatsby workshop that had around 1000 participants. After the workshop, I rewrote that same curriculum as online documentation (in the form of the new Gatsby Tutorial), which was getting around 4000 views a day.

With that one set of new docs, I’m able to reach as many students as if I taught four live workshops every day.

But as you scale your documentation and your audience grows, there’s a wider and wider variety of people you’re trying to write for. The bare-bones API reference that worked when your team was just a few internal engineers isn’t going to cut it when you have new users trying to use your product for the first time.

So how do you build one documentation site that works for all your users? In this article, I outline my top 5 techniques for creating high quality documentation that serves as many users as possible:

Expose the architecture
Set the stage
Let readers choose
Check for understanding
Get user feedback

Note: I’ll mainly look at this challenge through the lens of experience level. In other words, how can you create a documentation site that works for newcomers to your product as well as your existing power users.

Tip #1: Expose the architecture

In order for your users to make the most of your documentation, they need to understand the big picture of what kinds of information is included in your docs and where to find it. A major factor in that comes down to the information architecture of how your docs are organized.

Imagine you’re a user showing up to your product’s docs site for the first time. It might not be obvious to you where to find the information you’re looking for, or even what kinds of information is available to you.

As a documentarian, it’s your job to provide new users with a clear map and signposts that they can use to navigate the content of your docs.

Define the architecture

One example of an information architecture that you can use to organize your documentation is the Diátaxis framework by Daniele Procida. (This is what the Gatsby docs structure is based on).

The Diátaxis framework splits up documentation into four different categories:

Tutorials: Hold the reader’s hand through their first experience with your product. These are specifically tailored for newcomers who may not know anything about your product or how it works.
How-To Guides: Practical step-by-step guides to help readers accomplish a specific task. (Kind of like a recipe you would use for cooking.)
Reference: Describes the technical details of how your product works (like an API spec or a user manual).
Explanation: Explores more big-picture concepts and helps readers deepen their understanding of a topic. (Gatsby calls these docs “Conceptual Guides”.)

Expand for detailed image description

The four documentation types can be charted into four quadrants, based on their content type and intended use case.

Tutorials are learning-oriented. They include practical steps that are meant to serve our study (when we're in learning mode).
How-To Guides are task-oriented. They also contain practical steps, but they're focused more on serving our work (when we're actively trying to get something done).
Explanation is understanding-oriented. It's more theoretical knowledge, meant to serve our study.
Reference is information-oriented. It's theoretical knowledge that can serve our work.

The key thing about the Diátaxis framework is that it categorizes documentation based on the reader’s current goal. Someone using your product for the first time is going to need very different information from a professional actively working on fixing a bug for a client site. By organizing your docs in a way that centers your reader's end goal, you make it easier for them to discover the resource that they need when they need it.

Expose the architecture to your readers

It’s not enough to just sort all of your docs into organized categories. Once you have a structure in place, let your readers know what it is! This is where the idea of exposing the architecture comes into play.

For example, after we reorganized the Gatsby docs to use the Diátaxis framework, we adjusted the site's design to reflect the new information architecture:

On the docs home page, we tell readers what different types of documentation they’ll find on our site, and when each type is most useful.
We also list the four doc types in the navigation menu at the top of the page and in the sidebar, so that we can keep reinforcing our docs structure in the reader's mind.

Ultimately, it all comes back to helping readers find what they’re looking for more easily.

Tip: The "expose the architecture" principle can also be applied within individual docs! Use headings to break down the content within a doc. Within a particular doc type, use a consistent heading structure so that users know what to expect and can use their pattern-matching skills to parse information more quickly.

Tip #2: Set the stage

Now that your overall docs structure is in place, it’s time to zoom in and focus on the content within each doc. That brings us to tip #2: set the stage. In other words, help your users understand what you’re talking about before jumping into the weeds of explaining a new topic.

When I was a curriculum writer, my team had three things that we always checked for in each lesson that we designed: context, relevance, and application.

Context: Explain what you’re talking about, so that all your readers start with the same baseline understanding. This is where you define key terms and concepts, link to any prerequisite background knowledge you expect readers to have, and explain how the main idea of this doc ties fits into the overall structure of your product ecosystem.
Relevance: Why should readers care about this topic? What problem does it help solve? Are there specific use cases when they might choose to use this feature over another one?
Application: Walk readers through how to use the feature in their work.

Most docs already do a good job of the application piece, but the context and relevance pieces are especially important, because those are what help readers develop their mental model of how all the pieces of your product fit together.

An example

Let’s see what context, relevance, and application look like in practice. Here's how I used them in Part 3 of the new Gatsby Tutorial, which is all about plugins:

Context: What are plugins? Plugins are npm packages that let you add pre-built functionality to your Gatsby site.
Relevance: Why do we care about plugins? Because plugins let you add new features to your site more quickly than if you were to write them yourself from scratch.
Application: How do we add a plugin to our site? First, we install it with npm. Then, we configure it in our gatsby-config.js file. Finally, we use whatever unique plugin features are relevant in our site.

In your actual docs, you'd go into much more detail than this, but hopefully that's enough to give you an idea of what you're going for.

Having these three pieces nailed down early on in your writing process can help you stay focused and make sure your final doc will help all readers, regardless of how much previous experience they have with your product.

Tip #3: Let readers choose

This next tip is about giving readers multiple ways to consume information on your docs site, so that they can choose the option that works best for them.

Note: In education, this technique is called differentiation.

We'll look at two different ways you can give readers options: providing multiple forms of engagement, and letting users opt into additional details.

Multiple forms of engagement

By explaining the same concepts in multiple ways, you increase the chances that readers will find one option that resonates with their preferred learning style. And that means they’ll ultimately leave with a better understanding of the overall topic

In the new Gatsby Tutorial, in addition to the standard text explanations, we also include a variety of other ways that readers can engage with the main ideas:

Diagrams
Analogies
Video

Diagrams

Diagrams can help readers visualize processes, like this one that shows how data flows through Gatsby’s GraphQL data layer.

Diagrams are especially useful for complex technical systems or architectures with several moving parts.

Analogies

Analogies help map product-specific concepts that readers might not be familiar with onto everyday things that they’ve probably encountered in their own lives.

For instance, this illustration explains the difference between the StaticImage and GatsbyImage components using the analogy of asking for directions to a specific street address (like 400 Main Street) versus asking for directions to a generic location (like “the best coffee shop in town”).

Want to learn more? Maggie Appleton has an excellent talk called Drawing the Invisible, which is about visual metaphors and how they can make technical concepts easier to learn. (Ever wondered how React is like a potato plant? Check out this talk!)

Video

Some readers would rather follow along with someone as they work through the material. In that case, it can help to embed videos into your docs, showing someone walking through all the steps.

Each part of the Gatsby Tutorial includes an embedded YouTube video like the one below, where a colleague and I walk through the content for that part.

Note: Livestreams, analogies, and diagrams don’t replace the text in your doc. They complement each other. Each of these formats still require text to set the context and explain why this image or resource is relevant.

Opting into additional details

Another way you can provide readers choices is by making it easy for them to opt into or out of additional levels of detail.

In the new Gatsby Tutorial, we do this by making use of MDX’s ability to use React components inside of Markdown files. We have two different components that clearly separate extra optional content from the main flow of the document: announcements and collapsible sections.

For both components, the goal is to clearly indicate to users what content is required (the main steps of the Tutorial) and what is supplementary and can be skipped. That way, readers can tailor their experience through the doc to match the level of detail they’re interested in.

Announcements

In the Gatsby Tutorial, blue announcement boxes like the one shown below add extra information that stands out visually from the normal flow of the document.

Sometimes these callouts include Syntax Hints for JavaScript or React newcomers who might not be familiar with a particular piece of syntax. Other times they have Pro Tips which go into more detail about things that aren’t required for readers to know but that they might find interesting.

Tip: Adding consistent labels to your callouts is another way to expose the architecture of your docs to readers!

When readers are familiar with the types of callouts they'll see in your docs, they'll be able to parse through new docs more quickly. (Our brains are hard-wired for pattern matching!)

When you wrap this optional content in a visually distinct container, it helps readers who want to skip that content quickly see where to start reading again.

Collapsible Sections

The second component used in the Gatsby Tutorial is a purple collapsible box, which lets you hide content behind an expandable dropdown. (Under the hood, it's using the details and summary HTML elements.)

We use this to hide background information that might be helpful for React or GraphQL newcomers but that isn’t strictly necessary reading for people who want to just follow along with the steps of the Tutorial.

This would also be a good component to use if you wanted to document common error messages that users might encounter. For example, you could have the error name in the summary tag, and then users could click to expand for more information on what the error is and how to fix it.

Tip #4: Check for understanding

Once your users have found the doc they’re looking for and they’ve read the content, how do you know whether they "get" it? By adding in checks for understanding, you can use to make sure that your readers leave your docs understanding the things you were hoping they’d learn.

Checks for understanding are built-in opportunities for your readers to self-assess whether or not they understood the material in the doc.

Note: Depending on what information architecture you decided on for your docs, checks for understanding may make more sense in some types than others.

For example, if you're using the Diátaxis framework, checks for understanding may make more sense in a Tutorial or Explanation doc than in a Reference doc.

In the new Gatsby Tutorial, each part is book-ended by the following:

(At the beginning) A list of learning objectives, which outline what readers should be able to do by the time they finish reading the doc.
(At the end) Separate lists for questions (like a mini quiz) and key takeaways, to help readers reflect on whether or not they achieved the expected learning objectives.

Want an example?

Here are some concrete examples of these lists, from Part 4 of the Gatsby Tutorial.

Lesson Objectives:

By the end of this part of the Tutorial, you will be able to:

Use GraphiQL to explore the data in the data layer and build your own GraphQL queries.

Use the useStaticQuery hook to pull data into a “building-block” component.

Use the gatsby-source-filesystem plugin to pull data into your site from your computer’s filesystem.

Create a page query to pull data into a page component.

Summary Questions:

How do you get data into the data layer?

How can you see what data is in the data layer?

How do you get data out of the data layer?

What are the differences between a page query and useStaticQuery? How would you decide which one to use?

Key Takeaways:

Source plugins pull data from their original location into the Gatsby GraphQL data layer.

You can use the GraphiQL endpoint (localhost:8000/___graphql) to explore the data in the data layer and design GraphQL queries.

You can write GraphQL queries to pull data out of the data layer and into your React components.

To pull data into a “building block” component, use the useStaticQuery hook.

To pull data into a page component, use a page query.

These bulleted lists are a super low-lift option. But you could also do something more interactive, like having a CodePen or custom-built component to let readers practice the skills they learned. Apollo (where I work now!) has a learning platform called Odyssey that uses different kinds of interactive checks for understanding, including multiple-choice questions, fill-in-the-blank paragraphs, and embedded code challenges.

Regardless of the format, by providing opportunities for readers to self-assess how well they understood the material, you’re giving them a chance to strengthen their memories of the key ideas covered in your doc, which will make it easier for them to remember in the future.

Tip #5: Get user feedback

Once you’ve gotten all your docs in place, and you’re happy with how they’re organized and the content that’s in them, the only way you can know whether your docs experience is good or not is by hearing from actual users!

For the Gatsby docs, we have a feedback widget at the bottom of every page, which lets readers rate whether the current doc was great, fine, or bad. It also has a space for them to write in a comment, if they want to tell us a bit more about their experience.

All of those feedback responses get stored in a database, which is connected to a Gatsby site that pulls all the ratings and comments into a table. From there, we can look at overall trends and average ratings, to see which docs people really like and which ones need to be improved.

But ultimately, what’s more interesting to me is reading through all the comments that people leave.

Positive comments validate assumptions

Some of the comments are really positive, which is great for morale! But more importantly positive feedback helps us validate our assumptions about which things we thought would resonate with users.

For example, when I was rewriting the Gatsby Tutorial, one of the things I wanted to make sure to preserve was how the old Tutorial was approachable for readers without any prior React or GraphQL experience. And by reading through the comments on the new Tutorial, it’s been reassuring to see that several people have called out the fact that the new content doesn’t make assumptions about what people already know or use a ton of jargon.

Constructive comments lead to incremental improvements

But not all reviews are positive, and that can be a good thing! By addressing constructive comments and listening to user suggestions, you can make incremental improvements that gradually help make your docs experience better for your future users.

For example, the Gatsby Tutorial received one comment from a reader suggesting we add a “continue” button to the bottom of each page of the Tutorial, which was an easy fix to improve the reader experience. Other readers wrote in that they were confused about a particular aspect of CSS modules, so I added in an additional Syntax Hint announcement to explain what was going on under the hood. (And now we don't get comments on that anymore!)

Addressing constructive comments is also a good way to show your users that you care about their experience, and that you’re actually listening to their feedback. This helps build trust with the people in your community, which is always a good thing!

Wrap It Up

And those are my secrets for creating high-quality docs that work for both newcomers and power users!

To recap what we’ve covered:

It’s hard to make one docs site that works for everyone. But there are concrete steps you can take to improve your docs experience!

Expose the architecture, to help users understand the big picture of how your docs are structured.
Set the stage by making sure each doc provides context, relevance, and application.
Let readers choose what works best for them by explaining the same idea in a variety of ways, and make it clear when they can opt into or out of additional information.
Check for understanding by providing opportunities for self-assessment, through questions that align to each doc’s learning objectives.
Get user feedback so that you can validate your assumptions and continue making incremental improvements.

I hope that you learned at least one new technique that you can use to improve your docs experience for your users.

Have other tips that I didn't cover? I'd love to hear about them! You can reach me on Twitter: @meganesulli.

Resources

Linked in this post:

The official Gatsby Tutorial
Diátaxis documentation framework
Differentiation in education
Drawing the Invisible: How to Explain React through Visual Metaphors: Maggie Appleton's talk for Women of React 2020
What is "Pattern Matching"?
Apollo Odyssey

Additional resources:

Docs for Developers: An Engineer's Field Guide to Technical Writing (by Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, and Heidi Waterhouse): A great book for anyone looking to improve their documentation skills.

#DevEdBookClub Round 2: The Programmer's Brain

Megan Sullivan — Tue, 22 Feb 2022 07:21:10 +0000

It's time for our next round of our Twitter book club, and you're invited! Each week, we'll host a Twitter chat on Thursday at 6pm PT to discuss a chapter of The Programmer's Brain: What every programmer needs to know about cognition. We start with Chapter 1 on March 10.

Why join? Because learning is more fun together!

How to Participate

If you want to read along with us, here's what you need to do:

Pick up a copy of The Programmer's Brain.
Before the day of the Twitter chat, read the assigned chapter for the week. Jot down any quotes that stand out to you or questions you have.
On the day of the Twitter chat, hop onto Twitter between 6pm-7pm PT. Check the @DevEdBookClub Twitter account for the discussion thread.
Join the conversation (and tag your replies with #DevEdBookClub)! Check out what other participants are saying. Reply with your own thoughts, experiences, or questions. This is a great time to learn from each other and make new friends!

Schedule

Like to plan ahead? Here's when we're currently planning to discuss each chapter.

Part 1: On Reading Code Better

March 10, 2022: Chapter 1 (Decoding your confusion while coding)
March 17: Chapter 2 (Speed reading for code)
March 24: Chapter 3 (How to learn programming syntax quickly)
March 31: Chapter 4 (How to read complex code)

Part 2: On Thinking About Code

April 7: Chapter 5 (Reaching a deeper understanding of code)
April 14: Chapter 6 (Getting better at solving programming problems)
April 21: Chapter 7 (Misconceptions: Bugs in thinking)

(April 28: No Twitter chat this week. Catch up on the reading, or have a nice break!)

Part 3: On Writing Better Code

Part 4: On Collaborating On Code

May 26: Chapter 11 (The act of writing code)
June 2: Chapter 12 (Designing and improving larger systems)
June 9: Chapter 13 (How to onboard new developers)

General Wrap-up

June 16: General Wrap-Up / Final Thoughts

Have questions?

Leave a comment below, or reach out to us on Twitter!

See you on March 10!

Join our #DevEdBookClub!

Megan Sullivan — Tue, 02 Nov 2021 20:12:02 +0000

TL;DR

We're starting a book club, and you're invited! Each week, we'll host a Twitter chat on Thursday at 6pm PT to discuss a chapter of Docs for Developers, starting with Chapter 1 on November 18.

If you want to read along, you can pick up a copy of Docs for Developers. Or join us on the day to share your thoughts and experiences! We'll be hosting the chat from the @DevEdBookClub Twitter account, and we'll use the hashtag #DevEdBookClub.

Why join? Because learning is more fun together!

// Detect dark theme var iframe = document.getElementById('tweet-1453890429309489152-930'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1453890429309489152&theme=dark" }

How We Got Here

Once upon a time on Twitter, a bunch of people all posted that they'd picked up a copy of Docs for Developers. Among them were Aisha Blake, Christina Gorton, and Megan Sullivan, who serendipitously ended up in the same thread.

// Detect dark theme var iframe = document.getElementById('tweet-1450914087504957441-500'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1450914087504957441&theme=dark" }

They thought it would be fun to talk about the book as a group, to keep themselves accountable and share what they learned.

Thus, the DevEdBookClub was born!

How to Participate

If you want to read along with us, here's what you need to do:

Pick up a copy of Docs for Developers.
Before the day of the Twitter chat, read the assigned chapter for the week. Jot down any quotes that stand out to you or questions you have.
On the day of the Twitter chat, hop onto Twitter between 6pm-7pm PT. Check the @DevEdBookClub Twitter account for the discussion thread.
Join the conversation (tag your replies with #DevEdBookClub)! Check out what other participants are saying. Reply with your own thoughts, experiences, or questions. This is a great time to learn from each other and make new friends!

If you can't attend during the scheduled time, you can still add to the conversation after the fact. We'd love to hear your thoughts, whenever you have time to share them! We'll also be writing up a quick summary of the conversation here on DEV, for future readers.

Schedule

Like to plan ahead? Here's when we're currently planning to discuss each chapter.

November 18, 2021: Chapter 1 (Understanding your audience)
November 25: Break for Thanksgiving
December 2: Chapter 2 (Planning your documentation)
December 9: Chapter 3 (Drafting documentation)
December 16: Chapter 4 (Editing documentation)
December 23: Chapter 5 (Integrating code samples)
December 30: Chapter 6 (Adding visual content)
January 6, 2022: Chapter 7 (Publishing documentation)
January 13: Chapter 8 (Gathering and integrating feedback)
January 20: Chapter 9 (Measuring documentation quality)
January 27: Chapter 10 (Organizing documentation)
February 3: Chapter 11 (Maintaining and deprecating documentation)
February 10: General Wrap-Up / Final Thoughts
February 17: Special Q&A with the Authors

Have questions?

Leave a comment below, or reach out to us on Twitter!

See you on November 18!

How to be a Better Learner

Megan Sullivan — Mon, 02 Aug 2021 15:45:28 +0000

Introduction

Before I joined the tech industry, I worked as a tutor, a teaching assistant, a curriculum writer. And if I’ve learned anything from all my years of teaching, it’s that learning new things is hard.

Especially in the tech industry! As developers, we have a constant stream of new things to be learning, and every technology has its own quirks. Jargon! Syntax! Tools! It’s easy to feel overwhelmed, especially if you’re just getting started.

In this post, I’m going to talk about a few strategies you can use to learn more efficiently.

How We Learn

But first, I want to take a step back and talk about learning in general. The doodle below shows the progression of how we learn.

First, you start out in the developing stage. You’re still acquiring knowledge - maybe you’ve done a few tutorials. But you don’t have a lot of practice under your belt yet, and so you still need a lot of support to do anything substantial.
Once you’ve practiced some more, you move on to the competence stage. This is when you start to “get” it. You can do the thing, but it still requires conscious effort, or extra supports like checklists or cheat sheets.
If you practice even more, eventually you reach the mastery stage. This is when you’ve developed deep expertise in a subject. At this point, you understand how nearly all the pieces of the puzzle fit together, and you can do the thing without consciously thinking about it. In other words, you’ve developed automaticity (meaning you can do it automatically).

Tangent: Why Competence Isn't Enough

It can be tempting to stop practicing once you reach the competence stage, because you feel like you get it enough to get the job done.

But the great thing about achieving mastery is that, once you can handle the basics on autopilot, your brain is freed up to spend more time doing the hard work of creative problem solving.

I have a quick analogy to help illustrate what I mean. When I was first learning how to drive, I felt really overwhelmed by all the different things I had to keep track of. Was that dog on the sidewalk going to run into the street? Was that green light about to turn yellow? Was I too close to the car in front of me? There’s a lot to think about all at once!

But now that I’m a more experienced driver, my brain is able to process things like that dog and that light and the car in front of me without me even consciously thinking about it.

It’s not that I don’t see the same stimuli as when I was a beginner. But now, I’ve practiced driving enough so that I can react to all those things automatically. And that frees up my brain to wander and contemplate life’s real hard questions.

Tips to Maximize Learning

So we know that - with lots of practice - we can achieve mastery. But how should we practice, to make sure we’re spending our time efficiently?

The main strategies I’m going to talk about in this post are a combination of retrieval practice and feedback-driven metacognition. Basically, trying to remember things that you’ve learned, and then checking your answers to see if you were right.

1) Retrieval Practice

“The limiting factor for long-term memory is not retention (what is stored) but recall (what can be accessed).”

Greg Wilson, Teaching Tech Together

If you think about some typical study patterns (like cramming for a test, re-reading notes or textbooks, or binge-watching online courses) many of them focus on retention - trying to shove information into your brain. And even though that can feel productive, it doesn’t help much when you actually need to use that information.

Retrieval practice, on the other hand, is all about trying to get information out of your brain. Which is ultimately the skill you want to practice, since that’s what you’ll have to do when you’re trying to use what you’ve learned for your actual job or side project.

Let’s take a quick look at how memories work. Your brain has two different kinds of memory: working memory (sometimes also called short-term memory) and long-term memory.

You can think of your working memory as a backpack, where you hold onto the memory "books" you’re currently working with. It’s quick to access, but it’s not very big, so it can only hold a few things at a time. Your long-term memory is like a bookshelf. You can store a lot more information there, but it’s a bit slower to access, because it takes some time to find the book you’re looking for.

Retrieval practice is the act of deliberately pulling information out of your long-term memory and back into your working memory.

When you practice remembering a particular piece of information, your brain thinks, “Oh, we keep trying to access this memory, so it must be important,” and strengthens those neural pathways, which makes it easier for you to remember that thing again next time.

Studies have shown that using retrieval practice leads to better long-term retention of information than cramming or rereading. That’s not to say that retrieval practice is easy! It’s hard, and it can feel frustrating, like constantly having a word on the tip of your tongue that you can’t quite remember. But studies have also shown that the more challenging something is to learn, the better it is for long-term learning.

2) Feedback-Driven Metacognition

The second piece of this technique is called feedback-driven metacognition, which essentially means using feedback to reflect on your own thinking.

Put simply, this means checking your answer after retrieving it. So when you’re practicing, you should be constantly alternating between trying to remember some piece of knowledge, and then checking yourself to see if you were correct.

This feedback loop helps cement the things you already know, and it also helps you identify gaps in your current knowledge.

If we go back to the backpack analogy, when you use feedback-driven metacognition to check your retrieval, you give your brain a chance to update that memory. It’s like adding notes to the margin of your memory book, to correct a misconception or add some extra details. That way, the next time you retrieve that memory, there’s a bit more information.

Putting It Into Practice

Now that we’ve talked about what retrieval practice and feedback-driven metacognition are, let’s look at some examples of how you can put these strategies into practice.

"Read-cover-retrieve." Immediately after reading a section (or watching a video), cover up what you just read with your hand, and try to restate what you learned in your own words.
- For best results, try actually speaking aloud, so that your brain really has to go through the process of distilling and communicating the information. Remember, the more challenging you make it for yourself, the better it will be for your long-term learning.
Make flashcards to test yourself on key vocabulary or concepts. (Personally, I have a set of Git flashcards that I made for myself, with a command on one side and a diagram showing what it does on the other side.)
- Again, when you’re testing yourself, try to actually say your answer out loud first, as opposed to looking at the card, thinking, “Oh yeah I know this one,” and flipping it over to read the answer (which is really just rereading and not actual retrieval practice).
Do a brain dump. Get a blank piece of paper and write down everything you know about a topic. (This is also called the Feynman Technique.) You can make a concept map of key ideas, or you can write it out in words. The important thing is forcing your brain to articulate the concepts in your own words.

Take It to the Next Level

Congratulations! You now know the basics of retrieval practice and feedback-driven metacognition.

Now that we’ve covered the fundamentals, it’s time to turn things up a notch. Next, we’ll look at a few ways you can make your retrieval practice more challenging, which will help you remember things even better.

Pro Tip #1: Spaced Repetition

The first pro tip is to use spaced repetition, which means spreading out your practice over a several practice sessions. For example, instead of practicing a new skill for two hours all in one afternoon, it's better to practice for half an hour over the course of four days.

But why is that?

The graph below shows how the strength of a memory decays over time. It comes from a study by a German psychologist named Hermann Ebbinghaus. He memorized a bunch of random gibberish words, and then charted how well he was able to remember them at various time intervals.

Ebbinghaus found that the strength of a memory is strongest when you first learn it, then decays exponentially. It decreases the fastest in the first 20 minutes, then continues to drop for the first hour, and then eventually levels out after a day or so.

In other words, the more time that passes, the less you remember. Not terribly groundbreaking on its own. But what’s interesting is when you look at how this curve is affected by spaced repetition.

Ebbinghaus did another experiment, where he tracked the forgetting curve for his list of nonsense words, and then once he couldn’t remember any of the words anymore, he reviewed the list and started tracking a new forgetting curve. He repeated that process a bunch of times - learning, forgetting, relearning, forgetting again.

And he found that the rate of decay in each subsequent forgetting curve was actually slower than the previous ones. In other words, the act of remembering something slows the rate at which you forget it.

The key takeaway here is that, by giving yourself some time to forget between retrieval practice sessions, you’re actually strengthening those memories and making them easier to recall in the future.

Pro Tip #2: Interleaved Practice

The second pro tip is to use interleaved practice. In other words, mix up the order in which you practice different skills.

For example, imagine you're learning how to use a hammer and how to use a wrench. With interleaved practice, instead of doing all the nails first and all the bolts second, you’d switch randomly back and forth between the two.

You might be thinking that this seems inefficient. Wouldn’t it be faster to do all the hammering first and then do all the wrenching? You’re right, but remember that the more challenging you make your retrieval practice, the better your long-term learning gains will be. With interleaved practice, the focus isn’t on getting the job done as quickly and easily as possible. It’s about practicing how to choose the right tool for the problem at hand.

Try It Now!

Before you go, I want to give you one chance to try out retrieval practice for yourself.

Grab a piece of paper and do a quick brain dump of all the key ideas you can remember from this post. Ready? Go!

When you're done, click here for some feedback-driven metacognition.

The diagram below recaps the main concepts from this post.

How many did you remember? Which ones did you forget or misremember?

For a bonus challenge, try explaining each of these concepts in your own words.

Otherwise, I’ll leave you with one final thought:

Learning new things is hard. And you can do hard things.

Resources

Tips for Teaching a Remote Workshop

Megan Sullivan — Sat, 03 Apr 2021 03:50:04 +0000

Introduction

Last month, I co-facilitated a four-hour workshop at GatsbyConf. Although I've led many workshops in the past, this was my first time teaching remotely. We had over 1000 unique visitors, with around 250 participants at any given time for the full four hours. There were a few technical hiccups, but in general it went pretty well!

Want to watch the workshop recording? Check it out on YouTube: Getting Started with Gatsby.

Fair warning: There are some technical difficulties at the beginning. (And lots of vocal sound effects from me throughout. 😅)

In this post, I'll share some strategies we used to design an engaging virtual experience for students. I'll also highlight some things I'd do differently next time.

Before the workshop...
- Create a curriculum companion site.
- Use polls to gauge student engagement.
- Test your exact technical setup.
During the workshop...
- Recruit teammates to help moderate the chat.
- Be flexible.
- Bring your enthusiasm!

Before the Workshop: Preparation

Create a curriculum companion site

We decided to create a companion website that students could use to follow along with the workshop curriculum. This was likely the highest impact choice we made. After all, just because a teacher says something once doesn't mean that every student will understand and retain it. By summarizing the key points in a curriculum site, students could look over the concepts or code snippets at their own pace, even if they missed it in our slides or demos.

Think of the site as a virtual replacement for a textbook or worksheets. You can add as much or as little information as you think students will find helpful. For our workshop, we broke up the curriculum site into different pages - one for each section in the workshop. Each page had two main sections: Background and Exercises.

The Background section included explanations of key concepts, diagrams, code snippets, and links to relevant documentation. The content mirrored what was in our slides, with just enough extra description to put the ideas into context. To avoid overloading students, we only explained concepts that they'd need to be able to complete the exercises for that section.

The Exercises section included the prompts for all the student exercises, like what you might find on a worksheet. The goal was to help students stay on track. By giving students easy access to the exercise instructions, we avoided repeatedly answering the dreaded question: "What are we supposed to be doing right now?" Each exercise had the following pieces:

Instructions for the exercise.
- This should include a clear goal. What are students trying to do in this exercise? How will they know when they're done?
Hints.
- Point students in the right direction, without giving them the exact answer. For example, you could list out the general steps students have to follow to finish the exercise, without telling them exactly what to type.
Solution.
- Reveal the full solution for the exercise. (In our case, we linked to a specific branch in the GitHub repo for the example project.) If students finish early, they can check their work. Or, if they get stuck, they can use the solution to troubleshoot their own work.
Extra-credit challenges. (Sometimes.)
- Suggest ways to extend the original exercise. This piece isn't strictly necessary, but it's helpful for students who finish the main exercise early.

Want to see an example? The curriculum page on plugins is a good place to see the general structure in context.

Tip: You can use a <details> element to hide the contents of the Hints and Solution sections behind a dropdown toggle. That way, students can tailor the difficulty level to their own needs. If they want to challenge themselves, they can attempt the exercise without looking at the "spoilers." And if they want the extra help, they can open the toggle to get some more support.

If we'd had more time, I would have loved to add prerecorded videos to each section, where we'd explain key concepts and walk through exercises. That way, students could work through the content at their own pace, and our facilitation could focus more on answering questions and addressing misconceptions. (This style of instruction is called the flipped classroom model.)

Use polls to gauge student engagement

When you're teaching in person, you can read students' facial expressions in real time. You can sense whether the crowd feels engaged, confused, or bored, and you can adjust your instruction to accommodate their needs. But when you're teaching remotely and can't see anyone, you have to be more intentional about checking in with your audience.

Polls are a great virtual replacement for "reading the room." With a short multiple-choice question, you can quickly assess whether students are following you or not.

When you're planning your workshop, add in multiple-choice polls at key moments, like how you'd plan out exercises or examples. You can adjust your poll questions based on what you're hoping to learn about your students. For example, you might want to:

Gauge prior knowledge of a topic. Check how comfortable students already are with a topic before you start teaching.
- Example Question: "How much prior experience do you have with React?"
  - "This is my first time using it."
  - "I've tried it out but haven't used it extensively."
  - "I'm comfortable using it."
Check student progress. Use these after students have been working on an exercise to see how far they got.
- Example Question: "How far did you get?"
  - "I created a new site."
  - "I deployed my site."
  - "I got stuck."
Check for understanding. Ask students to self-assess how comfortable they currently feel with the material. Ask this after students have had some hands-on time with the concepts, like after an exercise or question-and-answer session.
- Example Question: "How comfortable are you feeling with writing GraphQL queries?"
  - "I get it!"
  - "I sort of get it."
  - "I don't get it at all."

Wondering how to gather student responses? Some conference hosting platforms have built-in audience polling features. But you can also use a tool like Google Forms or Slido to set up your questions ahead of time.

The way students answer a poll question should directly influence your next action as the instructor. For example, if most students say they didn't complete an exercise, you might decide to give them a few more minutes to work on it. Or, if many students said they weren't very comfortable with the material, you should probably find out what concept confused them and reexplain it with some different examples.

Test your exact technical setup

I present this cautionary tale, so you can learn from my mistakes:

A few weeks before our GatsbyConf workshop, we had a dress rehearsal to try out the conference-hosting platform with a fake test event. I practiced sharing my screen, audio, and video from my laptop, and everything worked as expected. Then, the night before the conference, I thought, "You know, I should add in an external monitor. That way, I can have the chat and my notes open while I share my laptop screen." I'd still be sharing from my laptop, so everything would be fine, right?

Narrator voice: "Everything was not fine."

On the day of the workshop, something about the resolution of my external monitor caused problems with screen sharing. Whenever I changed slides or switched between desktops, a bunch of weird visual artifacts showed up on the screen. Even though my screen looked fine to me, audience members couldn't actually see what I was presenting. And because I didn't see this issue until the actual workshop, my co-facilitator and I had to improvise a workaround so that we could actually teach the material. It wasn't ideal, and it significantly slowed down the initial pace of the workshop. Luckily, during one of the breaks, another teammate in the chat was able to help us troubleshoot and get us back on track. (Huge shoutout to Laurie Barth!)

The moral of this story is to test out your exact technical setup ahead of time, so that you don't have to fight with your technology on the day of the event. This includes monitors, microphones, headphones, internet connection, keyboards, lighting - any of the moving pieces that you're planning to use in the actual workshop.

During the Workshop: Instruction

Recruit teammates to help moderate the chat

If possible, have a few extra teammates sit in the session to act as teaching assistants (TAs) and help moderate the chat. When specific issues come up (e.g., a student gets an unexpected error message), ask the TAs to help them troubleshoot in the chat while you continue teaching. That way, students can get the individualized attention they need without derailing the entire lesson.

I didn't always do a great job at this hand-off in our workshop. A few times, a question in chat caught my eye, and I stopped what I was saying to answer the question myself, instead of passing it on to my other teammates in the chat. And in those moments, the rest of the students were stuck waiting for me to finish explaining something that wasn't relevant to them.

That's not to say that as the instructor you should never respond to the chat. If you see multiple people asking about the same topic, that's a good indicator that you may need to back up and re-explain something. But in general, consider the experience of the entire group before getting too far down a rabbit hole. Ask yourself, "Is answering this question in public going to help unblock enough people that it's worth taking the entire group on this detour?" If the answer is no, ask a TA to help debug, or revisit the question once the rest of the group has started work time for the next exercise.

Be flexible

I'm a big fan of effective time management. Before all of my workshops, I time how long it takes me to complete each exercise, and I use those times to estimate how long each section will take to teach. When I facilitate, I display timers during work time and breaks, so that students can self-regulate based on how much time they have left.

But in the end, it's also important to know when to throw out the schedule and make adjustments on the fly. If students are confused, it's okay to take a few extra minutes to back up and help them understand the big ideas. Show them another example or explain a concept with a different analogy. If you fall a bit behind schedule, skip one of the later exercises. Personally, I'd rather not get through all the material and have high rates of student understanding than rush to finish everything and lose students along the way.

It can be stressful to think on your feet in the moment, especially if things aren't going as planned. But do your best to stay calm and upbeat. Be kind to yourself. Remember, as the instructor, you're modeling the way students should behave when things go wrong. Show them that it's okay to make mistakes. Every mistake is an opportunity to learn something new. (Keep a growth mindset!)

Bring your enthusiasm!

This last tip applies to both remote and in-person teachers (and, more generally, leaders of any kind). In my experience, the instructor always sets the upper bound for the group's enthusiasm. Students will rarely be more excited about what you're teaching than you are. And even if they start out more excited than you, they're likely to tone down their energy level to meet yours. So it's important to set that bar high from the beginning.

Being an engaging speaker is just as much about how you say things as it is about what you say. If you sound bored by what you're talking about, odds are your students are also going to be bored and start reaching for their phones. Instead, speak clearly and confidently, in your best "teacher voice." If you feel comfortable showing your personality or incorporating a little humor, do it! It might feel silly at first, but that's okay. Setting the right tone is especially important for virtual workshops, where it's easier for students to tune out without anyone noticing.

Showing enthusiasm doesn't have to mean being insincerely peppy. If that's not your style, think instead about ways you can highlight what's exciting or game-changing about your subject matter. Why is this topic important? How does it tie into what students already know, and how might it help them in the future?

Nervous about public speaking? This is one way that virtual workshops are easier than in person: you don't have to see everyone! Try to do some calming exercises before the workshop starts, like taking deep breaths or stretching. I personally like doing a quick "shake down" to loosen up and boost my energy.

Things I'd Do Differently Next Time

Overall, I'm reasonably happy with how our GatsbyConf workshop went. But I do want to touch on some changes I'd make the next time around:

Overcommunicate expectations about pre-work.
- Many of the issues that came up in the first part of the workshop were related to problems students encountered when installing the necessary tools. We'd included installation instructions in the workshop description and asked students to complete them ahead of time, but we could have been better about sending out reminders. Next time, I want to clearly communicate that we won't be spending time in the workshop helping people troubleshoot their setups. Instead, we could hold an office hours session a few days before the workshop, where folks can drop in and get individualized help with debugging.
Set up contingency plans ahead of time, to unblock workshop attendees who have trouble setting up the tools or project on their own computers.
- A few days before the workshop, I tried to test out the curriculum by teaching it to my boyfriend. He wasn't able to install Gatsby on his laptop, which blocked him from doing the rest of the workshop. I started setting up a CodeSandbox starter project, so that he and other participants could have a controlled environment where they could work on the project without fighting with installers. But I was new to CodeSandbox and couldn't figure it out in time for the workshop. Next time, I'd like to prepare the backup plan in advance.
Provide opportunities for students to share their work.
- I had originally planned on having students each drop a link to their project in a shared Google Doc. I wanted students to be able to celebrate each other's progress, to recreate the sense of community you'd normally get from face-to-face interactions during an in-person event. Unfortunately, because we had so many workshop participants, there were too many people trying to access the doc at once, and it crashed. (Oops. 😬) Next time, I'll have to find a different solution that can handle more viewers at once.

Wrap It Up

Teaching a remote workshop can be a great opportunity to scale the number of people who see your work. But it also has its own set of unique challenges.

Here's a quick summary of the student engagement techniques outlined in this post:

Before the workshop...
- Create a curriculum site that students can use to follow along with the content.
- Use multiple-choice polls to check in with your audience and see what they need.
- Test your exact technical setup to avoid technical difficulties.
During the workshop...
- Recruit teammates to help moderate the chat, to act as teaching assistants and help answer individual student questions.
- Be flexible and make adjustments to timing and content as needed.
- Bring your enthusiasm, to keep students interested.

Do you have experience teaching remotely? Or have you attended a remote workshop as a student? I'd love to hear what other teaching techniques you've found especially helpful.

Nevertheless, Megan Coded

Megan Sullivan — Wed, 03 Mar 2021 23:18:22 +0000

Hi! I'm Megan. My pronouns are she/her. I've been a professional software developer since 2018, but I had a bit of a roundabout path into tech.

I majored in computer science in college. It was the first time I'd ever programmed, and I struggled with the content a lot at first. But even though I managed to get the hang of it by my senior year, I never saw myself becoming a professional developer. Looking back, I think that was partially because I lacked relatable role models and partially because I (mistakenly) thought being a dev meant being a socially isolated "code monkey" at a giant tech company.

In my senior year, I was also an undergraduate teaching assistant for the introductory CS course that I'd struggled with my freshman year. I loved helping students progress from feeling completely overwhelmed to gaining confidence in their own abilities. So I decided to go into education after graduation, because it seemed like more meaningful work - teaching had a direct impact on people's lives.

After college, I served a year as a City Year AmeriCorps member in New York City, where I supported a 3rd-grade classroom. I started an informal coding club, where I brought up a few of my students every day at lunch and helped them work through the Code.org Hour of Code curriculum on my iPad. When my year of service was over, I interned at Code.org on their Education team, where I worked on the pilot for their AP CS Principles curriculum. Then, I spent two years as a curriculum writer at Girls Who Code, a non-profit that focuses on teaching middle- and high-school girls how to code.

At Girls Who Code, each lesson we wrote for the curriculum included a "Woman in Tech Spotlight," where we'd highlight a woman in the industry and the cool ways she was using computer science to help her community. The goal was to help build students' sense of belonging while showing them all the ways that computer science can have an impact. After writing dozens of these spotlights over the course of two years, I slowly began to realize that I wanted to be a developer and create cool things too.

In 2018, I started my first entry-level developer position at a software consulting company called ThoughtWorks. I applied there because they had won multiple awards from the Anita Borg Institute for being the best company for woman technologists. I figured if I was going to have a good first experience anywhere, it was going to be there. Working at ThoughtWorks was a great way to level up my technical skills and learn best practices like pair programming (which we did exclusively), working in Agile sprints, and using test-driven development.

Today, I'm a senior software developer at Gatsby, where I focus primarily on documentation. I love that my job now is a blend of the technical and teaching skills I've developed over the course of my career. Now that I'm farther along in my journey as a professional developer, I feel much more confident in my own knowledge and abilities. But I also remember what it was like to be just starting out and feeling totally lost and overwhelmed. Part of the reason I started blogging was because I want to share what I've learned with others. I want to help other developers grow the way my teammates at ThoughtWorks and Gatsby have helped me.

Glad to have you along for the ride!