I'm Matthew Setter. I'm an experienced software engineer and a security researcher. I’ve been developing software since 2000 and I started this blog to help you write simpler, cleaner, and more secure software, with less effort.
Tech Content Needs Stories - Here's Whywriting January 14th, 2015
Stories aren’t just for little kids, they’re for everyone. With a story, you can show people how beneficial your services is. With a story, you can link in to an unsatisfied need that your reader’s trying to fill. Does your tech content have a story?
The day was long, like the two before it, yet the quest still wasn’t over. Forty-eight long, agonising, hours had passed since the search began. But you were still no closer to the result you’d been googling for; It felt like an eternity.
I’ve Found It, you exclaim, much to the surprise of your co-workers.
No, no you haven’t. It’s yet another post which gave you nothing. Dry facts, which suited one person, but annoyingly, frustratingly, not you.
You were sure that the problem couldn’t be too hard to solve, when you started out. But one search lead to another, which in turn lead to yet another. Each one seemed to have potential. Only it never worked out that way.
Each one was some, dry, “do this, then that, hey presto — you’re done”.
If you read the majority of the tech blogs that abound, the odds are high, very high, that you’ll get facts. But how often do they work?
How often do they take in to account the wide variety of circumstances, situations, and nuanced edge cases which modern computing necessitates?
Sure, there are some bloggers who both know what seems like everything, and also have the determination to share it, such as Matthew Weier O’Phinney, Joel Spolsky, and Martin Fowler. But how often do you find posts which cater just to one specific edge case, and nothing more.
How many posts do you come across which don’t provide any background or related information? Say 90%?
Ok, these statistics I can’t backup. They’re based on my own, subjective, experience. But I’m confident you can relate.
How Does This Relate to Tech Needing a Narrative?
Fair question. How it relates is that most technical posts play directly in to the computer nerd stereotype. They’re brief, even terse.
They tell just what the writer thought was relevant, the bare essentials of what they did to resolve their situation and nothing more.
But we need more.
We’re not computers, we’re not automatons — we’re people. We’re raised on stories, fairytales, and narratives. From the moment we’re born, we’re told stories; stories which communicate nearly everything we need to know.
From our history, our origins, the facts around us; almost everything in human history, at least 27,000 years according to LifeHacker, has been communicated this way.
Why do we expect computers should be any different?
Do You Want to Feel Like You’re Back in High School?
I feel sorry, genuinely sorry, for the majority of tech writers. Why? Because they remind me, all too often, of too many of my school classes.
In those classes, we were fed a never ending array of facts, numbers, places, and dates; information which was seemingly irrelevant!
One question was forever asked:
When will I ever use this?
So it goes in many tech posts. People write their thoughts down, but never give a rationale for why, how it relates, helps, or benefits the reader.
If you’re lucky, they’ve put the key facts near the start of the post and the header is reasonably indicative of what the post will solve.
But not many do.
Sometimes that rationale, or backstory, is absolutely critical; at the very least it can help a hell of a lot. Here’s a situation, you’ve only given enough information to cover the bare essentials which worked for you.
Here’s some suggestions:
- Give a backstory
- Explain your approach in some depth
- Provide links which helped you work out your solution
Not Every Post Needs a Story
I’ll be fair, not every post needs one; sometimes you can get away with just saying, from start to finish, do this, then that, then finally this — and you’re done.
But what if your situation, or explanation’s not that clear? What if someone doesn’t know anything about your library, your platform, your API, or your company? What if they’re completely new to whatever it is that you’re talking about?
They’ve jumped right in, attempting to fix a problem, yet for all intents and purposes they may as well be stumbling around, blindfolded, in an unlit room.
RTFM I hear you exclaim.
Sure, did you provide a link to it? Did you provide a link to supporting information, communities, and forums. Maybe you know the software inside out. Perhaps you’re a core contributor. But the reader won’t necessarily be.
It’s typical of software developers to either implicitly assume that others know as much as they do; or their actions infer that’s the case.
They give what they think is necessary, but aren’t aware of so many little, connective, aspects, which help round out a complete sense of understanding.
I’m not blaming people who do it (who hasn’t). But don’t be that person. Take the time to ensure that your posts has enough information for the reader to go further and step outside of your situation. Help them be able to help themselves.
That’s Why You Need a Story
Stories aren’t just for little kids, they’re for everyone. With a story, you can show people how beneficial your services is. With a story, you can link in to an unsatisfied need that your reader’s trying to fill.
With a story, you can convey to the user that this is the place to stop, that they’ve arrived at the answer to their issues, that the search is over and they can soon go home.
Stories are what we as people relate to best. Yes, you’re busy. Yes you have places to be. You might be fooled in to thinking that no one’s interested in stories, that no one has time for them. You’d be wrong.
How many movies do you watch — what’s central to all of them — the story.
Make Sure Your Writing Has a Story!
If it doesn’t, it’s likely not getting traction with your audience; hell, you might not even have an audience. That’s a pity, because I’m sure you have something great to share. But if you’re not writing the right way, no one may ever know.
Join the Email List
If you enjoyed this post, why not join the email list and get all future posts straight to your inbox? In addition, you'll get background information, extra research, and other content that's only available on the list. I promise I'll NEVER spam you. And you can unsubscribe at any time.