Let's blog more about technical writing

Jul. 15, 2022

I’ve been wondering for a while why I don’t see more blogs on technical writing, tech comms, and technical documentation. I’ve been in listening mode for years, and beyond Tom Johnson’s excellent blog, it’s hard to find more content around technical writing. I’ve some hypotheses as to why that’s happening, as well as a request: We should be blogging more about technical writing and tech comms.

Are we too few and hard to find?

Let’s start with the first hypothesis. Is there really a lack of technical writing blogs and blog posts? Hard to tell without dedicated crawlers like Technorati, but some quick searches in Google seem to confirm that impression. Technical writing doesn’t seem to be that popular in the blogosphere, and is not a Twitter topic.

According to the U.S. Bureau of Labor Statistics, there are 52 thousand technical writers working in the United States as of 2020, whereas software developers number 2.2 million employees, not counting hardware engineers. That’s a ratio of 43 developers per technical writer, which seems to relate to the proportions of blog content in Google.

Does that alone explain why there are fewer blogs on technical writing? I’m not sure. Other issues might be at play, such as the lack of cohesion when it comes to terminology (is it “tech writing” or “tech comms” or “content strategy”?), as well as dominance of programming content over other types of content. It might be that technical writing blogs are just hard to come by, possibly owing to a low popularity / high scarcity combo.

Doesn’t all this means we should be raising the volume? I think it does.

Is our professional self-esteem too low?

Another hypothesis to explain the lack of technical writing blogs and content is that our profession is not that interesting. In the words of a fellow technical writer, technical writing “is just a job”, which is true, but doesn’t explain why other technical jobs get much more exposure in media and social networks. Are we working in perpetual awe of engineers? Do we think of our work as secondary or menial?

Source: https://ocean.si.edu/ocean-life/sharks-rays/oceanic-whitetip-shark-and-pilot-fish

Are we the pilot fish of software engineering? I sincerely hope not.

Posts on technical writing and technical documentation regularly get featured on Hacker News’s top page, and technical writing as a profession is booming pretty much everywhere. We’re in increasingly high demand, yet we keep ourselves off the radar, unable to train others in our craft, and somewhat silent except when it comes to Write the Docs conferences. It might be that our professional self-esteem or self-awareness is low.

Scorning non-writers when they say that writing docs is easy comes natural to any tech writer, though it’s nothing more than a passive-aggressive defence against the lack of recognition toward our profession. We can do better. Let’s be proud about what we do. Let’s be positive and give devs a little bit of our sunshine.

Is our craft too difficult to explain?

Writing about writing is hard. Writing about technical writing can be even harder, especially after long weeks of writing for a living. No wonder, then, that tech writers prefer to write about other stuff, or even jump to science fiction (like Kurt Vonnegut or Ted Chiang). That’s fine, though it contributes very little to shining light upon what we do at work.

Mysterious as we are, we leave software developers to go full cargo cult on tech writing

It’s not just writers who need to know. Software engineers, our peers, regularly struggle with documentation and require guidance. Sites like StackExchange or Hacker News are ripe with questions on technical writing. The lack of fresh, authoritative resources on the topic lead developers to create their own cargo cult versions of tech writing, which is great as a start, though insufficient for all else.

While there is nothing particularly magic about technical writing, the lack of signal about what we do and how we do it not only makes explaining our job a more difficult task, but it also hurts our employability. We clearly know what we’re doing: Let’s talk about it with strangers, eh?

We should be blogging more

I’m a noisy Italian guy who’s been blogging since 2003, and I’ve written blog posts for a living for many years. You’d say I’m used to it, so of course it’s easy for me to say that we should be blogging more.

Let me tell you this: anyone can blog. Your opinion on technical writing is valuable. Your ideas can be, too.

Technical writing needs more visibility and more conversations happening. I believe tech writing is more than drafting manuals: After reading this study, I realized that technical writing might be one of the last bastions of rational discourse, a happy island of objective language used for enabling things in reality. We need more of that, everywhere.

Making your voice be heard helps generating discourse. Adding yourself to the conversation increases the diversity of voices and opinions. You don’t have to be an expert. There’s no need to fight off impostor syndrome: embrace it, blog about it. Blog about your learning path. Blog to comment or answer on something cool you’ve seen. Or tweet. The pace doesn’t matter: it’s not like you’ve to launch a newsletter!

Paraphrasing Tom Johnson’s blog, we could rather be writing.

Read on: A love letter to technical writing.