Speak like a human: 12 ways tech companies can write less-corporate blog posts

TL;DR: Blog posts are a great way to tell users about ships, but it’s all too easy to fall back on the marketing speak we’re inundated with each day. Instead, use these tips to write user-centric posts for your corporate blog.
8 minute read

If there’s one thing that corporations are consistently good at, it’s talking like a corporation. We’ve all seen it: you’re reading a blog post about an “innovative, new” this or a “first-of-its-kind” that, and before you realize it, although your now-glazed-over eyes may still be moving over the words, you’ve stopped reading entirely. You know marketing speak when you see it. They’re not talking to you. They’re talking at you, and the only thing they’ve successfully convinced you of is of your need to never visit that marketing-site-disguised-as-a-blog ever again.

Thankfully, it doesn’t have to be that way. Corporations are fully capable of talking like humans do, at least the humans that make up that company are, and unsurprisingly customers respond positively when treated with that kind of base-level respect. If you’ve ever read the GitHub Blog, you’ll hopefully notice that at GitHub, we pride ourselves in “being human”. Not “delivering authentic experiences” or “speaking like a human”, but actually being a gosh-darn human talking to other humans. There may be a corporate logo at the top of the page, but blog posts are still exclusively written by, and read by living, breathing humans. My name is on the post and it’s simply me, as an individual, talking to customers. No corporate buzzwords or filters needed.

A big part of that philosophy, and an even bigger part of reducing it to writing can be attributed to @kcwatkins who introduced me to the idea that markets are conversations. Your users don’t read your blog to be marketed to. They read your blog to learn about what’s going on with your product, and the most effective way to convey product information — to educate current and potential users about a ship — is to be part of that ongoing conversation (that happens with or without your participation), not to stand on top of a hill shouting mindless marketing speak. Put another way, if you wouldn’t do it in real life — say when bumping into a customer at a coffee shop — why is it okay to do on your corporate blog?

Think of the typical corporate ship post. It probably starts something like this:

Today, after months of effort, we’re excited to announce our new wiz-bang feature…

Here’s the thing: Your users don’t care how excited you are. They don’t care about how much effort you put in. They don’t care how hard it was to do. All they care about is one thing: how does it benefit me?

Having helped my fellow GitHubbers to post to GitHub’s blog for the past couple of years, here are a dozen simple rules1 you can adopt for writing human, user-centric ship posts for your own corporate blog:

1. It’s not shipped until you blog about it

If you start from the premise that markets are conversations, then the best person to talk about a new feature on behalf of your company is the person who shipped it, not someone from your marketing department. They know what the feature does, why you built it, and what users need to know to use it. Developers can talk about the technical details of the implementation, without the juicy bits being lost in translation, and designers can give a peak into their creative process with rich visuals, all things your users are interested in much more than any pretty-sounding marketing fluff any copywriter could possibly dream up.

There’s also something to be said for giving the person that shipped the new feature the opportunity to take a public curtain call. After all, developers are people too and shipping is contagious. Developers should author posts themselves (with help copyediting, if needed), and the post should be in their own name. Anonymous posts are a great way to signal to users that its a corporation speaking at them, not a human talking with them.

2. Write for users, not for yourself

I’m sure what you do is super interesting. But what’s even more interesting is what a user can do now as a result of your work. Instead of telling your users how excited you are or how much work it was for you to implement the new thing (written from your perspective), tell the user why your work matters to someone using your product (written from the user’s perspective). A simple rule of thumb is that there should be more use of the word “you” than of “we”. An even better rule of thumb is to avoid using the word “we” in the first place.

3. Describe the 1/4” hole

Your post should focus on what a user can do, not on what the thing you built does. Let’s say I have a picture that I want hung on the wall. I’ll likely go to a big-box retailer to pick up a quarter-inch drill. But in reality, I couldn’t care less about the drill. What I’m really after is the 1/4” hole — the thing the drill ultimately enables me to do. Yet, most technology companies produce digital drills.

Rather than spend time telling me how great your drill is, describe the holes it produces. Show me how well it hangs pictures. Plant the seed in my head for all the great things that I can do with the drill. Airline commercials have pictures of exotic destinations, not cabin interiors. Liquor commercials show people out having a great time, not the underlying grains being grown. When announcing a new feature your post should be almost exclusively about the better hole it empowers the user to create, not the new drill bit they now need to buy.

4. The title should summarize the entire post

In the typical corporate blog, the signal-to-noise ratio is usually pretty low, at least in terms of things any one given user cares about. Even if a blog is exclusively used to announce new features, there’s a good chance that I have no use for whatever feature you’re talking about. No matter how good your creative team is at coming up with clever or link-bait style post titles, the title should summarize the entire post for the reader.

The idea is to forecast what the post is about and give the user an early escape hatch to bail if they don’t want to read any further. The post is for the reader’s benefit, and assuming you don’t have ads on your site, you’ve got nothing to gain by tricking them into clicking your link. Let users opt in to reading your post, rather than coercing them though cleverness or semantic slight of hand.

5. The first sentence should be the one thing you want the reader to know

The first sentence of the post should, when combined with the title, further summarize the post. This should be the one thing that if the user stopped reading right then, that you’d hoped that they’d take away. Think grammar school style inverted pyramid. Put the most important things up front and go from there in decreasing order of importance. With a few exceptions, your post should almost always describe what you shipped, how to use it, and why it matters, in that order.

Readers have an extremely short attention span and even less time to spend reading something they don’t care about. Imagine a power curve with 80% of readers reading the first sentence, and the probability of a reader continuing dropping off sentence-by-sentence from there. You should assume that readers will take less than 30 seconds to read your entire post, and less than three seconds to decide if they’re even going to get that far. Write assuming 80% of your readers will only read the first sentence. What do you want 80% of readers to know if you can only tell them one thing?

6. An animated GIF is worth 10,000 words

The best blog posts are short on words and long on visuals. You could spend 1,000 words describing what the new button looks like, or you can just show me a picture of it. Better yet, create an animated GIF of what happens when I click it. Have fun with it. At GitHub, we often hide Easter eggs in screenshots. Think hints of unreleased features or a scene from your favorite movie. The abstract concepts often involved with ships are easier to describe visually and helps the reader to put themselves directly in the shoes of the user, rather than in the shoes of developer trying to describe what a user might do.

7. Focus on the one new thing

A blog post gives an idea a URL. It’s the thing that I can link to in perpetuity to explain to others what action you took and why. It’s how I share with my colleagues that I’m excited about a new feature. When you start sneaking multiple ideas into a single post, or go off on a mini-treatise about the virtue of why you produce widgets, you’ve broken that one-to-one relationship. Keep posts limited to one single idea, the smallest, most granular idea possible. If you find yourself needing to explain two distinct concepts, ship what you’ve got before going any further. Feel free to split things into multiple posts. Last, focus on what’s new, not what used to be. Avoid apologizing or even mentioning the previous state of things. The post is about what’s new, not what’s changed.

8. Remove unnecessary words

If you can remove a word, phrase, sentence, or paragraph without the post losing its core message, it needs to go. Facts > fluff.

9. Don’t use the word “today”

It’s an easy crutch to begin a blog post with “Starting today…”. That’s like staring a speech with “So I sat down to think about what to write and…” The thing that separates blog posts from just about any other medium on the web is the fact that they have a date at the top, a date which allows them to serve as a snapshot in time. If you write something in a post, users are going to assume it’s something timely. In practicality, when launching something new, the word “today” often takes the place of more valuable information, like how to actually use the darn thing. When you leave out “today”, you’re forced to actually describe what’s changed.

10. Under promise, over deliver

It’s tempting to talk about what’s still in development, but don’t tease your users with features that they can’t yet use, and thus gain nothing from. Generating “buzz” is noticeably self-serving, and your users will respond accordingly. Not to mention, it locks your developers into particular decisions, even if you subsequently gain information that suggests it’s ultimately not the right direction for the product. Instead, manage expectations, both internally and externally.

This corporate anti-pattern is especially common in the world of closed-to-open source. “We intend to open source X” may be a great forcing function internally, but more often than not leaves your audience asking why it took so long in the first place. “We open sourced X” or “You can now Y” is a much better start to the conversation.

11. Embrace structure

It’s a well known fact that people on the internet do not read words. They may read a sentence or two, but given a few hundred words, they’re all but guaranteed to be skimming after the first sentence. Optimize the post’s structure for ease of readability. Use lots of descriptive headings, keep paragraphs short, and rely on large images to break up text when necessary. Lists should always be bulleted, not comma separated, and links to resources, especially past announcements, should be peppered throughout, providing visual contrast to key concepts.

12. Always provide an out

The user has read your post, you’ve gotten them excited, now what? What’s the call to action? What’s their ideal first click you want the user to make after reading? Put it right in front of them. Make it opt-out to do the right thing. It may be documentation describing in detail how to use the new thing, or may be a link directly to the new thing itself. Either way, the idea here is to nudge the user in the desired direction. You can’t blame them for not doing it if you don’t make it ridiculously easy. Assume people are lazy.

In addition to the above, grammar, spelling, tone and style go without saying. There are many style guides out there, but 18F’s seems to be the most web-centric among them. When blogging, you should be writing for the web (links, informal tone, etc.) and you should use the opportunity to show some corporate personality. Even better, collaborate using CI and Git flow.

From infomercials to press releases, we’ve been trained to think corporations must speak a certain way, but that’s far from the case. In fact, corporations don’t speak. The humans that make them up do. It’s a challenge to unlearn the anti-patterns that surround us, but it’s possible to foster a corporate culture whereby interacting with users is seen as a conversation, not a shouting match amongst competitors. Follow these rules, empower your humans to talk to other humans, and your users will respond accordingly.

  1. Some of these rules are adopted from GitHub’s own internal blog guidelines, a document that was originally authored well before 2012 when it was added to version control, but git blame suggests credit should be given to @defunkt, @kneath, @tnm, @holman, and @kcwatkins among likely many others. 

Originally published July 20, 2015 | View revision history

If you enjoyed this post, you might also enjoy:


Ben Balter is the Director of Engineering Operations and Culture at GitHub, the world’s largest software development platform. Previously, as Chief of Staff for Security, he managed the office of the Chief Security Officer, improving overall business effectiveness of the Security organization through portfolio management, strategy, planning, culture, and values. As a Staff Technical Program manager for Enterprise and Compliance, Ben managed GitHub’s on-premises and SaaS enterprise offerings, and as the Senior Product Manager overseeing the platform’s Trust and Safety efforts, Ben shipped more than 500 features in support of community management, privacy, compliance, content moderation, product security, platform health, and open source workflows to ensure the GitHub community and platform remained safe, secure, and welcoming for all software developers. Before joining GitHub’s Product team, Ben served as GitHub’s Government Evangelist, leading the efforts to encourage more than 2,000 government organizations across 75 countries to adopt open source philosophies for code, data, and policy development. More about the author →

This page is open source. Please help improve it.