Going on 15 Years of Explanatory Writing
I was doing some personal archeology recently and dug up the earliest available screenshot of a blog post that I wrote.
Side note: This is an explanation of an 'SAT problem', part of a test highschoolers take in the U.S. before college. I can see the seed of my professional life there-- learning new things and teaching them on the go.
That blog is dated Sat, Nov 28, 2009, which means I'm going on my 15th year of writing to help other people learn! I haven't blogged consistently since then, but in the interim I have written essays, articles, teaching resources, study guides, and even... yes, poetry, which is not explanatory but is still great writing practice. I've been back at blogging for a few years now in the tech world. And here's what I've learned.
Write from your experience
This might sound obvious. But being in touch with your own experience is vital to good explanatory writing.
I'm not living some Hunter S. Thompson-esque lifestyle (I moonlight as a mom to very young children), I'm just in tech and learning in public, but people resonate with that.
If you've run into some gnarly bug that revealed itself to be your user error, I can almost guarantee you that you're not the only one who's been there. But if you're being intellectually courageous and pushing the boundaries of what you can do, you might be the first one to write about it!
Be relentless
I remember it being tough for me to find the answer to that SAT problem. I had to sit down with a pen and a piece of paper and write every step out, then I had to ask someone (my dad) to double-check it for me before it whooshed off to the presses. Anyone remember Blogger? I digress.
It typically takes me about an hour to get a blog draft out, but that's not counting the hours I took coding some project that is either the subject of the blog or the background experience for it.
And it's certainly not counting the review process. Technical review is a serious practice, and if you're pushing the boundaries of what you know (or of what folks in the space in general know, say, going beyond documentation on a subject) a single technical review can change the direction of a blog post.
All this work is 100% worth it to craft a well-written, authentic blog post.
You can always get better at writing
Nothing excites me more than one of my Google dos with a pile of comments and suggestion in the sidebar. I mean that sincerely. I've grown to have a certain amount of confidence in my own writing, and seeing improvement suggestions means that I'm just about to get that much better.
Find reviewers who will push you to become excellent in terms of both structure and syntax. If you're out of those at the moment, I recommend Verlyn Klinkenborg's Several Short Sentences About Writing as a start.
For technical writing: not everyone is there for your prose
A lot of these learnings are about writing in general. But audiences of technical blogs are sometimes there for one thing: the coveted code snippet that will get them one step farther in their project.
Include code. Do it carefully, as you don't want it to interrupt the narrative, but thoughtfully, since you want people to be able to find the essentials.
Enjoy it, or not
Good writing comes from well-worn habit, but it also comes from an author who is passionate about their subject. Try to write about something you enjoy doing. But if you're writing about something you hate, like a terrible experience you had with library compatibilities, that can be great fuel for the fire as well. Just remember to be kind and fair to others in your written assessments, always.
Who's your audience?
Maybe I should have put this first. Save the best for last? Anyhow, understanding your audience is maybe the most critical part of writing because it affects the structure of your writing.
Every piece of technical writing has an entry point and an exit point. This means that you must make assumptions about what your audience knows and doesn't know, there's no escaping that. But being intentional about it is key.
I'm not finished
But this blog post is. I set a timer for this one, but perhaps, once I finish this 15th year of writing, I'll come back and write some more about these and other things.