A glimpse into the context through which I create educational content and tutorials.
View in Sanity Studio2023-12-13
I’ve been making websites for ages and writing tutorials and blog posts for a while. For the first time, educating developers is now my actual job as my role at Sanity has moved to principal educator.
So here’s my not-very-organised, brain dump of thoughts I’ve leaned upon as a content creator, primarily for educating developers on behalf of a product. You might find this context useful for your technical education content.
Writing educational content is different from writing documentation.
In the context of documentation, you’re writing a comprehensive manual for the entire product broken down into its smallest pieces.
Educational material is more like applied documentation, where it is more beneficial to be specific about the context in which you would implement those features. It’s more beneficial for people looking for examples and inspiration that match their jobs to be done.
Suppose we consider documentation pages “points of interest” on the journey of getting the job done. Developer educators create “trail maps” and hold students’ hands, threading together multiple concepts on the road to completing the goal.
The audience I’m typically writing to are people hired by a company that is already using – or evaluating – Sanity. This is not the same audience as those who excitedly try it out over the weekend for a side project. So, I do my best to meet them where they are. There's a high likelihood that they have no preexisting knowledge of the product, but have inherited an existing code base and have a list of specific problems to solve.
With a super flexible product, it can be challenging (or impossible) to generalise so that every student sees themselves in the lesson. So, it is best to remove as many uncommon elements as possible.
In some early workshops, I taught in a collaborative, browser-based coding environment, but no one spent their 8-hour workday there. The concepts I was teaching were removed from the average feeling of their day-to-day. The disconnect was too high a price to pay.
For these reasons, I write guides and exercises as close as possible to real-world scenarios that readers are likely already in. I agree with Wes Bos that examples should avoid nonsense like foo, baz in favour of actual – and universally understood – concepts and contexts.
“Lorem ipsum” is out, too. Get ChatGPT to generate some fake copy if you need it.
Your student is already learning a lot of new concepts, syntaxes and more while onboarding to your product. Don’t overload this learning curve with unrealistic or unfamiliar hypotheticals. Make sure educational content is as closely aligned with real-world jobs to be done as possible.
In the earliest workshops I taught, a challenge would be set with links to the documentation and a time limit to solve it. Or, you could watch me work my way through it. I had hoped that the friction of looking up the answers would embed some new skills.
It didn’t take long to notice that most people would wait until I had finished, entered my CodeSandbox link, and copied the solution, which gave them the gratification of seeing the impact of that piece of work.
So, is it better to make someone experience reward through the challenge – or provide a faster route to success?
Adult learners hate feeling stupid.
In subsequent workshops, I’ve promoted a path to getting more done faster. The skills likely aren’t as “sticky” as a result. However, the feeling of going from zero to 100 is a more positive outcome from the lesson.
Now, every training module I write contains complete, copy-and-paste-ready code snippets.
The same training materials taught in these workshops are available to watch and read later when students wish to review or repeat what they have already done.
Perhaps what I’ve enjoyed most from running workshops is the invaluable feedback that acts as a forcing function to continue to iterate on the material.
This isn’t always pleasant!
You can spend too much time crafting examples you think will hit just right, only to discover you’ve missed the mark. Be prepared to challenge your assumptions and test in production. Gather feedback and iterate again.
I’d already been using Sanity for several years before creating educational content. I mistakenly considered myself my audience and thought it most valuable to develop extreme examples of the most advanced use cases.
That’s what I’d want!
Not quite. While advanced demos are impressive, nothing beats getting the fundamentals right. I’ve even found this when consuming learning materials on platforms I already use. There’s likely some part of the API that you overlooked or misunderstood, and it’s thrilling to know that just a tweak to what you already know can sharpen your skills even further.
There will always be an audience for advanced topics. But it’s a smaller one. Focus on reinforcing the fundamentals first.
It’s often not enough to demonstrate a product feature. We all bring experiences and biases to the table when learning something new —especially those already familiar with the platform that may be introduced to a new feature or breaking change.
For both new and experienced learners consider how you might need to first teach them how to think before what to do.
Additionally for those with experience consider what they may need to unlearn. What is no longer true, and both the benefits of – and the method how – to implement what’s new.
Perhaps this is controversial, but I'm not talking about the “always be closing” hard sell here. Consider this through the lens of helping developers find their seat at the table to convince others to implement their preferred technology.
Sanity is an extremely developer-friendly product. So, it easily excites developers who try it out on their own and then hope to use it at their place of work. However, developers are not always the decision-makers regarding large organisations’ architectural choices.
So, to use the tools they prefer, developers may need to practice being convincing, especially to untrained audiences. The skill to demonstrate your favourite technology’s value – and not the feature set – to others is crucial for broader acceptance.
This is also extremely useful in the case of Sanity because it is developer-friendly for the sake of better content creation experiences.
Understanding value is to swap saying, “If I use Sanity, I will be happier,” for “If we use Sanity, we will all be happier”.
Learners who invest time in understanding your product more deeply should increasingly value that investment and look for returns.
Therefore, a firmly established and highly educated user of your product is more likely to advocate for the platform with which they’ve spent time learning and have a high degree of confidence using it.
I had the opportunity to ask Kent C. Dodds for some advice about being a better educator. His immediate response was to "put a box around Sanity", and this is true of any platform, problem or subject matter.
Don't overcomplicate examples and tutorials with external information that's not specifically related to the solution. Draw attention to the value of the outcome, don't distract your audience with optional side quests or complicated examples or dull feature walk-throughs.
Was this helpful? Got any other thoughts? Let me know!
