A Florida man saw a problem in his neighborhood. As a designer, he was bugged by something he saw every day. So he decided to fix it.
He grabbed some supplies from his closet, then hopped in his car to do something he’d been wanting to do for a long time.
I won’t spoil it because the short video itself is very good. Remember, he’s a designer.
Now, I’m no designer, but as I watched it, I thought about things I’d like to fix, too.
The video appealed to me as a writer who sees words all day long that I wish I could change. Because on the web, if it’s not your site or Wikipedia, chances are you’re stuck with it.
There’s no spray paint on the internet.
But if I could take a massive edit button to every technical tutorial, for example, here’s what I’d change.
Specifically, these three headings:
- Introduction: remove the heading and edit the intro to set the context, not to say “in this tutorial”
- Prerequisites: since this isn’t a course catalog, either remove or say it simpler, like “What You Need”
- Conclusion: make this an action, the most important thing you’d say to someone who read the whole thing
These may seem like pet peeves (and they are), but they’re also signs the tutorial doesn’t know its job. For technical content to be effective, you need more than some technical words and code.
The introduction sets up why these steps you’re about to walk them through matter. The conclusion tells them not just what they’ve learned, but what they should do next. If there’s not a clear next step, why are they even following your tutorial?
I found an example post and recorded a short walkthrough to show what I mean.
In Conclusion 🙄, search your tutorials for these terms, then ask yourself how it’s helping the developer who reads it.
If you’d like an actual strategy behind the technical content you produce, my team may be able to help.