As I work on my next course, Authoring and Maintaining GitHub Actions, I am working through the storyline.

Wait – a storyline? Aren't technical courses mostly boring fact dumps?

NO – a thousand times NO.

The best courses use a narrative-driven story to pull the learner in and engage them.

I remember taking Neil Gaiman's storytelling Masterclass and recently also went through Michael Lewis' storytelling Masterclass. You don't have to do that because I'll just tell you some of the elements of what makes a good story:

  • Conflict: You cannot have a story without conflict. This creates tension and keeps the reader engaged. People want to know what happens. You can create conflict easily by laying out something a character wants and then not giving it to them. One of my favorite quotes from Gaiman from the class was, "I never give my characters what they want, but I always give them what they need."
  • Characters: Even in non-fiction, you need characters. In Moneyball, Michael Lewis treats the Oakland A's GM (Billy Bean) as the main character. Interestingly, he specifically says it can be compelling to make people the reader normally doesn't think are important into the heroes. The heroes in the book are not the athletes who normally get all the attention.

Yes there's more to it than this but that's basically it – you need to create some kind of conflict and introduce characters into your technical content.

But... how do you actually do it?

Personally, I often make the learner the "hero" of the story, usually putting them in the shoes of a team lead. But the other characters are perhaps more subtle: a fictitious company, other teammates, or even the tech itself (great for debugging stories).

When I think about how to present a topic that could be bland, like GitHub Actions, I try to think about what the learner wants. I craft a use case that would make sense in their context. What the learner wants usually is "just show me the code." However, that's not what they need. They need a learning experience.

So I create tension (and drama) by teasing them about what they want and how we'll get there.

Example: Authoring GitHub Actions

My course is going to teach people how to author their own GitHub Actions. What the learner wants is to prepare for the GitHub Actions exam so they can get certified – the purpose of the learning path on Pluralsight is to get them there.

When I look at some other courses around this exam, one thing that stood out to me was the lack of actual implementation. The thing is... you can read the docs on GitHub and prepare for the exam yourself. Learners don't need me if that's all they want.

What they can't get from watching videos and what they need to really prepare for an exam is hands-on experience. This isn't a lab; it's video training, so the best I can do is provide a real-world, end-to-end demo of authoring an action and publishing it that is grounded in their context (most PS learners are enterprise software developers). I'm also providing a GitHub Codespaces dev container so they can follow along if they don't want to install anything on their local machine.

The demo action I chose solves a common problem on teams: getting notified when their CICD pipelines are done.

Example slide from my course laying out the problem

At Target, we used Slack notifications. However, it would always post to a channel – it never actually notified us. Channels get messy and people ignore them. It would be ideal if we could somehow either DM or tag the original author.

This is the conflict/tension I create in the story: there are already GitHub Actions that can post to Slack – but trying to take that extra step of notifying the author who triggered the Action workflow is missing (and would usually depend on the specific structure of your org).

I tell the learner we'll solve the problem with a custom action:

Example slide laying out the problem from my course

So now we have conflict and characters (the learner, Globomantics, the custom action). This forms the narrative and backdrop for the course—it ties all the conceptual stuff together through demos, and it's something I can call back to and discuss with the learner. It applies the knowledge I'll share with them to an actual use case that should be relevant to them and provides motivation to learn.

Have a lovely day,

Storytelling in technical courses

Hint: Tell a story

Want devs to love your product?

Hi 👋 I'm Kamran. I'm a consulting developer educator who can help your DevRel team increase adoption with better docs, samples, and courseware.
Sign up