Writing for HTML Newbies
I started teaching at the community college here in town last semester. It’s fun! I love hanging out with students (virtually in these current times) and watching metaphorical lightbulbs flash above their heads when a new concept sinks in and makes sense for the first time.
It’s also incredibly humbling. As someone who has been pushing pixels for the better part of 15 years, I’m realizing that I don’t always have all the answers to the questions that students ask. Even more humbling, I sometimes struggle to clearly explain an answer when I do have one.
That brings me to writing about the web, or more accurately, writing about the web for beginners.
I’m in the middle of preparing curriculum and lesson plans for a beginning-level course on HTML and CSS. I already know that there’s a high bar for technical writing in general because that’s sorta what I do everyday as editor over at CSS-Tricks. I take someone’s complex idea and help shape it into something that most front-end folks can (hopefully) understand. Still, I’ve found it difficult to convey even the most basic of HTML concepts, like the difference between block and inline elements. If you’re reading this, you probably already know the answer in your own head. But, go ahead and try to explain it to someone who has just cracked open a code editor for the first time. It’s hard!
In fact, writing for beginners is a craft in and of itself. At least, that’s what I’ve come to learn. It takes a level of empathy, patience and adaptability to pull it all together.
Provide a roadmap
It’s one thing to get someone started on their journey in web development. But it’s a completely different thing to let them know where they’re headed.
I’ve found that providing an outline of the course materials is a huge help. Not only does it give students a way to contextualize what we’re discussing, but it almost acts as a roadmap that I can use to show students where we are and how the things we’re discussing fit into the bigger picture of where we’re going. A class is not a suspenseful novel where reading ahead ruins the story; it’s more like a road trip where knowing what’s ahead helps get students to the final destination.
Write with a friendly tone
Technical information is a lot easier to grok if you can form a relationship with the reader. Sure, you want to maintain a professional demeanor and establish yourself as an expert on the topic. But that doesn’t mean a haughty tone and an academic lexicon is the way to go about it.
I have to fight this one often. I have a tendency to write like an academic in my own personal writing and I’ve learned that I have to meet students somewhere in the middle — if not even closer to them — to effectively make a point or explain a concept. Technical jargon isn’t gonna work if there’s no basis for understanding that technical jargon in the first place.
Take small steps
Oh man, it is super tempting to jump from one exciting thing to another when it comes to writing about HTML. It’s like, “Alright, we spent a little time on writing paragraphs in an HTML document but now let’s dive right into images! And links! And embedded media!” And so on.
But there’s no sense in rushing. Teaching for the web is not a race to the finish, but again, a series of steps that ultimately lead to a destination. It’s more like, “Alright, we you just wrote your first HTML paragraph but now we’re going to walk through the many options we have to format that text.”
There’s no such thing as “too small” when it comes to explaining a concept. The difference between an HTML element and an HTML tag is small, but significant. Did you know that inline HTML elements can be combined? You probably do. But giving someone this information up front is what helps form good habits early in the learning process, which helps usher in better semantics and accessibility as a whole. It’s our job to pass that on.
Use pictures, or paint them with your words
We’ve all heard that a picture is worth a thousand words. Or is it a million words? Meh, I forget.
The point is that they work. Simple screenshots can help, but taking extra time to create assets that clearly illustrate the concepts being discussed is ideal. The more lovely the image, the more tempting it is to look at.
We can also paint pictures with our words. Rely on things like metaphors and similes, to drive home an idea. Again, technical information is already tough to grok. Having something to relate it to can be the difference between knowing it and getting it.
That’s all I’ve got for now. Like I said, I’m still early in the process of writing the curriculum for this class. But my experience in the last semester taught me some valuable lessons about what it means to teach students and how it’s different from simply passing information along.