Finally! I just published the latest updates to the internal Brain Traffic editorial style guide—and it took nearly five whole months. Gasp! I’m a content professional! You’d think maintaining a set of guidelines about stuff like grammar and word choice would be at the top of the fun list for a word nerd like me.
But, it’s not.
Like most people responsible for a style guide, I find making updates seems to be a task always languishing at the bottom of my to-do list. After all, updates are rarely urgent. And collecting all those changes, deciding which ones to make … it all seems so exhausting.
Still, a useful style guide is an updated style guide. And, organizations need useful style guides. So, here, especially for you (and a little bit for me), is a pep talk about keeping your style guide in tip-top shape.
See what can happen when you don’t use a style guide?
(Image courtesy of Above the Law)
Why style guides are awesome
An editorial style guide provides standards for written content, typically on items such as grammar, punctuation, and spelling. Before we begin, we must first acknowledge the power of a good style guide:
- It’s key to editorial consistency across your organization’s content (along with a good editor, copyeditor, and/or proofreader who enforces it).
- It saves you from deciding style items on the fly. So when conversations flare-up over whether “email” should have a hyphen, you can simply respond, “Our style guide says no hyphen.” End of discussion. (Or, suggest dissenters submit a proposed change for the next style guide update—more on that later.)
- It’s essential in helping new writers and content creators get familiar with your organization’s writing style. For the same reason, freelancers and contractors will adore you—we’re talking putting your picture up in their locker—for having an updated style guide.
What to put in your style guide
The first step to defining your internal, or “house,” style guide, is to choose your preferred external style source. This is going to answer the bulk of your users’ style questions. Old favorites are The Associated Press Stylebook and The Chicago Manual of Style. However, we use the incredible and amazing Yahoo! Style Guide. It’s specifically written for digital communications and includes great info like writing clear user-interface text and coding basics.
With your external style guide defined, your house style guide only needs to cover:
- Style preferences that differ from the external style guide
- Example: “Internet” has an initial cap per the Yahoo! Style Guide, but our house style uses “internet.”
- Style items or topics that aren’t covered in the external style guide
- Example: The Yahoo! Style Guide doesn’t include a preferred spelling for “wireframes,” so we’ve defined it as one word.
- Items that people ask about frequently or often get tripped up by (meaning, it’s a frequent question or issue for more than just one person)
- Example: We just added an entry on when to hyphenate a compound modifier.
- Note: You don’t need to fully define these rules if they're explained well elsewhere. Our guide has some brief rules on hyphenating compound modifiers and then a link to an external site with more in-depth guidelines.
Consider adding these “guiding criteria” to your style guide so everyone understands what’s included in the guide. These criteria are essential to helping you evaluate proposed changes and updates.
You’ll also want to define clear sections of the style guide for different types of information. Common divisions include:
- Terms (preferred spellings and usages)
Other topics you could include:
- Trademarks, and when to use them
- Tone and voice guidelines
- Web-specific items (for example, how to indicate a required field on a form)
To keep your style guide as simple as possible (both for users to use and you to update), only include topics or sections that your users really need. Think “need to have,” not “nice to have.”
Define the updating process
Here’s the first rule of updating your style guide: Do it as little as possible. Yep, I’m serious. It can be a lot of work. Besides, frequent updates can be hard for users to keep up with. At Brain Traffic, we aim for once a year.
Next, you need a style guide committee who will decide on changes and updates. Everyone on our style guide committee loves words, writing, and appreciates a good style rule—which makes them perfect. That said, keep your committee small, maybe five people at the most. Because wrangling lots of opinions about lots of changes is, well, an awful lot.
It’s also important to create an easy process for users to submit proposed changes. Our style guide is a wiki, so users can post their comments/questions/challenges in the document. At the start of an update cycle, I put these in a spreadsheet along with any other changes I’ve been collecting. Whatever your method, make sure your users know how to submit a proposed change—this can go directly in your style guide, too.
After you’ve collected these changes, get the committee together to decide what changes to make. There will be lots of opinions, and even lively discussions. But remember this:
- Use your “guiding criteria” to evaluate every proposed change.
- Consider the impact of the change. If you add a hyphen to “email,” how often does it already show up in your content hyphen-less? How much work will it be to change this across your organization and your communication channels—and is it worth it?
Announce the style guide changes to your users after you’ve updated the guide. This is essential. How will they know “e-mail” now has a hyphen if you don’t tell them?
The Keeper of the Style Guide
To keep the process running smoothly, you need one lucky soul to be the Keeper of the Style Guide. This person is in charge of everything:
- Getting the update cycle started
- Collecting the changes and getting the committee to discuss and decide on them
- Making the actual changes to the style guide—or making sure the changes are made
- Communicating the changes to all of your style guide users
Remember, the Keeper of the Style Guide gets to wield the Power of Style over a multitude of users. Exciting, yes? So: Go! Fight! Win! Let the style-guide updating begin!
Posted in Web Writing
Perhaps I’m distracted, maybe I’m tired. I’ve read this copy three times and I still don’t know what it’s talking about. I must not be focusing. Maybe I need more coffee …
Or maybe, the problem is the copy itself. Ah, yes. I see it now: jargon. Obscure, technical terms I think I should know, because the copy keeps using them, but I don’t (what’s a “drive-by download”?). Words that sound impressive, but may be uncommon, and therefore vague, to a general audience (think “erudite” instead of “well-read”). Buzzwords that have been used so much—and so badly—that their meaning is diluted (like “innovate”).
Nothing kills content like jargon. Here are three ways you can make sure it doesn’t end up in your content.
Speak your audience’s language
Before you start writing, stop and deliberately consider what words your audience does and doesn’t use in their daily language. If your audience is IT professionals, it makes sense to use IT terms with them. But if you’re talking to small business owners who need IT services, using IT terms is confusing, meaningless, and inconsiderate.
When in doubt, remember: Simple, common words cover a lot of ground with any audience, because everyone immediately knows what they mean. And they’re especially important to low-literacy readers, who are more common than you may think. Learn more about them in Angela Colter’s article, “The Audience You Didn’t Know You Had.”
It can be easy to fall into using buzzwords or words with vague meanings. Let’s take an article about writing training, for example. I could start by saying, “Optimize your writing skills and leverage your business.” But what does that mean? Could a reader even guess at what I’m saying?
It would be better if I was more specific, like “Learn to write concise copy that customers read and respond to.” Language that’s precise gives readers a clear idea about what they’re going to read next. This is especially important when you’re writing high-level information that leads to more detail.
Know what you’re talking about
The jargon problem can be about more than just word choice. To write clear and useful copy for readers, you need to be an expert on the audience, and on what you’re selling. Or at least have expert-level information.
Vague language can be the result of vague ideas, so before you start writing, make sure your expert information includes:
- Who the customer is
- Their hopes and desires
- The problems they want to solve (goals)
- How this product/service/idea meets their needs
If I’m struggling to write clear and convincing copy, I sometimes find I don’t know enough. Sure, I may have product specs and a customer profile, but if I stop and listen, I hear questions nagging at the back of my mind. What’s so special about this product? Aren’t there a dozen others like it? What’s driving my audience to seek this information? What questions do they have in their minds?
Show your readers you know who they are
Stick your feet in the reader’s shoes. It really is the real purpose of your copy: to show the audience you took their shoes (OK, borrowed), you’ve got them on, and you did a 5K in them. Because if you understand their needs, and exactly how your product/service/idea meets those needs, then that’s all you need to tell them—in concise, simple terms. And that is far more compelling to your readers than a thousand fancy words.
Posted in Web Writing
(Click image to enlarge.)
Before CNN scrolling news headlines. Before aggregators. Before Tweetdeck.
Way back in 1940 the Brockton Enterprise newspaper was providing a handmade news feed to passersby on the street: by posting headlines in its office windows.
I spotted this picture in a blog post of vintage color photos. I had no idea that newspapers had ever done this, and I don’t know whether it was a common practice. But what a great strategy for selling papers: entice people with the headlines so that they want to read more.
It makes me wonder how often they updated their “feed.” Every time the daily edition was released? As soon as a story broke? Did people purposely visit, or “subscribe” to, this corner to find out what was going on in the world?
Oh, and who was the lucky one hand-printing all those headlines and pasting them up in the window? Clicking “publish” never seemed easier.
The method may be old-fashioned, but the strategy is as modern as, well, today’s headlines.
Posted in Editorial Strategy, Uncategorized, User Experience
My suburban neighborhood is pretty typical, with the exception of the 200-acre wooded park in the middle of it. I live right on the edge of the park, which means deer, ducks, pheasants, and turkeys roam near my house. And I enjoy that.
But a certain turkey has really started getting in my way. Literally.
He often hangs out on the corner of a four-way stop. At first it was funny, like he was waiting for the bus.
Then, this weekend as I approached the stop, the turkey was in the middle of the intersection. I waited for him to cross the road (I see the joke here), but he had other ideas. He headed right for my car and proceeded to block me every time I tried to swerve around him. He was so close I couldn’t even see him until his blue head popped up over the hood and he "gobble-gobbled" at me.
It was ridiculous. And maddening. I had no idea what to do. I wasn’t about to get out of the car—turkeys are surprisingly large. And this one clearly had no fear.
I finally escaped, and then I called Animal Control, who said, and I quote, "We’re aware of the turkey."
Apparently, even the local news had heard about this traffic-stopping bird. Police hadn’t been able to catch him. They even hired a professional trapper. And guess what? His trap was stolen.
Why? Because the neighbors like the turkey. They’ve been feeding him. They think of him as their mascot. They’ve even called city hall to protest his capture. They love this turkey so much that they are willing to put up with the hazards and annoyance this turkey imposes on, well, me.
So. Do you have any turkeys on your website? Let’s discuss.
A navigation "concept"
Website navigation helps users find the information they’re looking for. Sometimes.
The Flash-powered navigation on thomasedison.org includes an impressively long list of Edison’s inventions. But it literally spirals and moves as you use it, and the font is so small it’s illegible. I want to know more about Edison, but the design is getting in my way.
Here’s another example: The tiny gray boxes at the top of the site for fashion designer Alexandre Herchcovitch may look sleek, but as unlabeled navigation they tell you absolutely nothing about the content—unless you click each one. (P.S. Incredibly loud intro music and no off button? Isn’t that against the law?)
Give me what I’m looking for
If you give me a text link, make sure that when I click I get whatever the text tells me I will.
If a "Read more" link on a "Project Management Courses" page goes to a video, that video should give information on course content. It shouldn’t just show course participants saying "hi." This is only interesting to the people in the video.
And the video ending, showing a participant in his underwear and covered with Post-It notes, helped me decide to never sign up for these classes.
Show, don’t tell
Don’t fall victim to the "blah blah blah." Just give me the goods.
Ladder Golf site visitors are likely interested in ordering this new game or learning how it’s played. So the homepage doesn’t need all kinds of content telling them why the product is so great. Instead, move that animated banner demonstrating the game from way at the bottom of the page to the top, and give visitors what they want.
Too much fun
If you’re looking for product information on the Beggin’ Strips dog snacks site, you’re in for some unexpected fun. Play games! Put a picture of yourself and your dog in a music video! Lots of fun—and no actual product info anywhere. Hmm. Bacon-flavored turkey?
Why did the turkey cross the road?
I don’t care. Because it’s not funny.
Do you have turkeys on your website? No matter how fun, cute, or beautifully designed a turkey is, if it keeps users from getting to the information they want, then it’s causing an annoying, even aggravating, experience.
Think of it this way: Does anyone want a turkey getting in their way? No, they don’t. Trust me.
Posted in Content Strategy, User Experience
Recently, our IT company sent us an email alert about "scareware" messages, warning that clicking on any of these messages could install some nasty malware on our computers.
Here’s what they look like:
"The text reads: Warning!!! Your computer contains various types of adware and viruses.
"Your system requires immediate anti-viruses check! Personal Antivirus will perform a quick and free scanning of your PC for viruses and malicious programs. "
"The text reads: Your computer remains infected by threats! They can cause data loss and file damage and need to be cured as soon as possible."
Graphically, these warnings look legit, like they were created with Microsoft or another professional anti-virus company, right? It’s enough to scare people into clicking immediately.
The Copy Test
Fortunately, there’s a simple trick for detecting scareware: Take a look at that copy.
Do legitimate warnings ever work to inspire this much fear and urgency? Do they scream "emergency" with multiple exclamation points and words like "malicious" and "infected"?
No. And that’s what gives them away. Legit error and warning messages are rarely this exciting.
While it’s not great writing, the writers of this scareware copy understand their readers and their fear of computer viruses. Many "for real" error and warning messages don’t work because the writer isn’t thinking from the readers’ point of view.
Pop-ups and error messages should be clear and compelling (but not frightening!). Check out these tips for writing some good ones.
The Morals of This Story
Posted in Resources, Web Content, Web Writing
1. We have a soft spot for hobos and pioneers.
2. Our favorite lunch spot is the Bulldog NE. But we doubt we’re their favorite customers. (Maybe if we called ahead before all 15 of us stomped through their doors …)
3. We’re really, really happy about our new dishwasher. Magically clean dishes.
4. We’ve had a TV for 6 months that we haven’t taken out of the box.
5. All meetings involve snarky comments. It’s why we have meetings.
6. Hilarity is one of our core values. For real.
7. Our fridge is stocked with string cheese, English muffins, sparkling water, Diet Coke and V8.
8. Kristina thinks V8 is gross. David, Julie and Elizabeth strongly disagree.
9. We love the fake grass in our conference room table.
10. Meghan and Elizabeth hate each other. Elizabeth says Meghan eats kittens. True story.
11. We’re almost out of beer for Disco Friday.
12. For Amy and Angie 1.0′s birthdays, we ordered a Pride & Pegasus birthday cake (e.g., Jane Austen on a pegasus). Best birthday cake ever.
13. Our receptionist team includes Liberace, T Rex, and a cow. We had to fire Buffy the Vampire Slayer because she was dressed inappropriately.
14. Erin and Meghan are in a fight.
15. We really, really, really want to hire more guys. We love dudes. And equal opportunity.
16. We love it when dogs visit the office. Our favorites: Molly, Wahoo, and Sam.
17. Chunks of things fall from our ceiling.
18. Delivery dudes, please pay attention: No one named Brian Traffic works here.
19. But if you are named Brian, and you’d like to work here, please let us know.
20. We have very loud shoes. We are the loudest walkers in the history of anyone who walked.
21. Favorite shoes around here: Danskos (particularly favored by IAs), MBT shoes (the anti-shoes), and Fluevogs.
22. We made our own Christmas stockings.
23. We work in the old Banks building. Many clients and visitors remember shopping here before it was turned into office space.
24. We’re within spitting distance of the Otter, Popular Front, and White Castle. But we do not spit on any of them.
25. We like chips.
Posted in Around the Office
You may remember Kristina's post about style guides. Style guides make writers happy because they can follow the rules the first time, and they make businesses happy because the writers are speaking the language. And hammering out style details at the beginning saves needless time and expense to clean up these small details at the end of a large project.
As such, we writers have regular discussions about troubling words or troublesome tasks of cleaning up misunderstandings about capitalization, em dashes, and the like. Here's one of the latest, when we officially decided not to initial cap “internet” anymore, whether it’s used as a noun or an adjective.
As I recall, the decision came about something like this:
Angie 1.0 (me): Hey, everyone! Should we initial cap internet when we use it as a noun?
Angie 2.0: I don’t like capitalizing Internet. Or Web. Or InterWebs.
Katie: Yeah! I hate capping things.
Meghan: But didn’t we agree to initial cap “web” when we use it as a noun?
Angie 2.0: When did we agree to that?
Angie 1.0: Didn’t you get that email?
Meghan: Wired magazine doesn’t initial cap internet. And isn’t the rule about initial capping it in the process of changing?
Angie 2.0: And Wired is on the cutting edge of that change.
Angie 1.0: Right. Eventually nobody will initial cap internet.
Erin: Once the dictionaries catch up.
Meghan: Yes, let’s be on the cutting edge of change!
Angie 1.0: Remember that movie The Net with Sandra Bullock?
Erin: Wasn’t that about identity theft on the internet?
Angie 2.0: Yeah, something like that. Do we have to initial cap “Net” when we use it as a noun?
Katie: We are NOT using “the Net.” Under any circumstances.
A quick perusal of a few industry blogs revealed an inconsistent style on initial capping internet. So we turned to Wired for some guidance. In 2004, it declared that on its pages internet and web (and net) would not be initial capped anymore. We’re happy to officially join the trend—since we believe it will become a rule anyway.
It’s definitely becoming a rule in our house style guide.
Posted in Around the Office, Editorial Strategy, Style Guides and Such, Web Writing
Some nytimes.com readers aren't so happy with the video content in this blog post:
The video communicates the point of the blog post, which follows up on a story about an opera singer's weight loss. A couple of the reader comments perfectly capture the problem:
Oh, come on, we have to click on the video to find out how she's doing? Why not say, "She's maintaining her weight loss. Click on the video to find out how she's doing it," or "She's begun gaining the weight back. Watch the video for more details." Don't leave those of us who can't see and/or hear the video in the dark like that please.
And, sadly, this:
Can't get the video to load..
There are a dozen reasons why someone can't or won't watch a video. Keep those users in mind if you're using video to communicate essential content. If you want them to get your message, you'll need to provide it in an accessible non-video format. Like, say, text.
Posted in Content Strategy, Editorial Strategy, Web Writing
Here's a transcript of a recent grammar conversation we had via an all-staff e-mail that was jumpstarted by Angie King (Angie 2.0). It includes such unrelated subjects as manbabies and Vitamin Water.
Read the rest of this entry »
Posted in Web Writing
When I came to Brain Traffic as Employee #4, communication was refreshingly easy. I could greet the entire company with just one “good morning.”
It was really different from the large corporation where I’d previously been employed. A lot of changes took place over the seven years I was there, but one thing never changed: Every annual employee satisfaction survey named communication as a top challenge.
Follow-up feedback to the survey results pointed to communication problems between departments. People just didn’t understand the goals or processes of other departments, which created problems when those things affected their work. And it made them crabby.
So I was happy thinking the challenge of poor communication was behind me.
Except that it wasn’t.
Feedback in a vacuum
I didn’t recognize it at first. But there it was in the feedback for projects from large companies. Reviewers we’d never met requested—even demanded—changes that seemed all wrong. For example, they’d turn our succinct, tight writing into ugly, awkward run-ons filled with jargon.
Sabotage? Well, no. More likely these reviewers don’t know what makes good web content and why. They’re involved only because they’re subject matter experts, and their subject is appearing on the site.
If our internal contact does a good job explaining the goals of the project to their internal partners, then this problem may be averted. But sometimes there’s a mentality that says, “You don’t need to know about the web project and its goals. Just make sure the information is right.”
And there it is: poor communication.
The solution is in the meeting
So here’s what we do at Brain Traffic to combat this: At the very beginning of a web project, we have a kick-off meeting with everyone. That means everyone who is going to submit, review, and approve content.
At this meeting, we introduce the what, why and how about good web content. We explain why web writing is different from print writing. We talk about the basics of good user experience. We reassure them that our intent is not to one-up, override, or otherwise disregard their input and concerns. We help them see, from the vantage point of the user, why concise content is way better than lengthy, complex jargon.
We’re not saying this approach solves all communication problems throughout the web content development process. But it has really helped us:
Engage content stakeholders
Uncover questions or concerns about scope or schedule before everyone’s committed
Identify other content providers or reviewers who’d been overlooked before
Connect with people in person so that they know there are actual human beings writing their content and receiving their feedback
Think it’s too hard to get everyone together at once? Then hold a series of meetings. Get people on the phone. Try as hard as possible to engage everyone who’s going to touch the content as early as possible in your process.
Believe me, it’s easier than undoing (and arguing about) uninformed feedback and revisions in the 11th hour of your project.
Posted in Content Strategy