Every so often I’ll write a blog post to put into words what I’ve learned over the years. It’s been a while, but here are a few posts I wrote for tech writers, professional writers, and companies that need a writer.
Whose App Can Tell You Where Your Writing is Weak
Ernest Hemingway’s. That’s right – Hemingway. Well, actually it’s an app created by Adam and Ben Long (both brothers and writers), but it’s called Hemingway App.
It’s a quick and easy way to see where your writing needs work. If you read my post a couple months ago on How to Lighten Up Your Writing, you remember I called out what can make your writing feel heavy to readers – junk words, poor tense words, and adverbs. Well, this app calls them out and then some. Just enter your text, and the app highlights the weak spots based on the following criteria:
- YELLOW: complex sentences requiring college-level reading skills
- RED: complex sentences requiring post-college reading skills
- BLUE: adverbs
- PURPLE: overly complex words
- GREEN: passive voice
As you can see, the app calls out adverbs and passive voice for you (two of the things I called out as “heavy writing”) as well as anything you could easily simplify. It’s kind of like the Microsoft Word feature where it tells you the readability score – which it does as well, except it shows you which words are at fault so you can easily fix them.
To try it out, I figure what better test than my write-up on How to Lighten Up Your Writing. So I copied the text, pasted it into the app, and prayed I didn’t make a fool of myself. And what do you know? The majority of highlights showing where the writing was weak are examples I wrote to show what not to do. Not bad. As far as the other words highlighted by the app, I stand by some and left the others to show how easy it is to overlook your own writing.
Keep in mind, the highlighting is based on an algorithm, so don’t swear by it. However, it’s great for doing a last minute read-through – especially when a deadline approaches.
According to the creators, when it came to naming the app, “We automatically thought of Hemingway,” Adam said in an interview with ABC News. “His short, declarative sentences. If you just cut out long words, wordy constructions, it makes the piece much more powerful.”
Truth be told, even Hemingway’s work doesn’t always score well, but I very much agree when it comes to professional writing – simple and concise for the win.
Where to Go for Grammar Answers
Even though your website will launch in a few hours, you still find yourself making edits to the About Me page. The content looks good enough and hell it should be since it’s what you know the most about, but you’re not sure if you used “accept” right or if you should capitalize “account manager” and you definitely don’t want to look like you have no idea what you’re doing. So instead of dusting off old textbooks (assuming you even kept them) or trusting answers on Yahoo (hint – you shouldn’t), use the tools below to find quick and reliable answers to your grammar questions.
Grammar Girl on QuickAndDirtyTips.com
Grammar Girl is actually a podcast created by Mignon Fogarty, but she also publishes articles on www.quickanddirtytips.com – a website worth checking out. Each Grammar Girl article focuses on a single grammar rule, so if you search for “affect vs effect” on her site, you’ll find an article by her called “Affect Versus Effect.” It explains the difference between the two without being wordy and gives a few examples. No more scouring the internet for a simple answer to a common question.
Some of her other popular tips include “I.e. Versus E.g.” and “Apostrophes and Plurals.” Most of the time, I don’t even need to search her site; I can just Google the grammar rule. She’s usually the first result that pops up. Now maybe that’s because Google knows me before I know me, but it’s largely due to how simple and direct her topics are.
And why is she better than Yahoo! Answers and so many others? Grammar Girl won the iTunes Best Classic Podcast award in 2013 and Writer’s Digest 101 Best Websites for Writers in 2012. I can trust that.
Chicago and APA Style Websites
These sites are a bit more serious, but are also associated with the two most common style guides adopted by professions and businesses: Chicago Manual of Style and APA style . If your company uses a specific one, I would recommend getting a subscription to that style’s site, but until then you can find FREE answers to your questions using the resources below without a subscription to their sites:
Chicago Manual of Style Q&A Section
The Q&A section of their site is a list of user-submitted questions answered by the manuscript editing department. They tackle questions not answered in the manual or found in a dictionary and range from the very specific to the more general opinion. Browse through the questions freely or search for a specific topic. You can also submit a question or sign up for monthly alerts still without a subscription. Keep an eye on the Tools section of the site as well.
The APA Blog is similar to the Grammar Girl site in which a team of APA style experts write weekly articles on writing, but more specifically on publishing and the APA Style. The tone of each article depends on the writer, which may be a turn-off, but with a great search and category section, it’s pretty easy to find the article that answers your question. And if you’re still unsure of an answer, you can also submit comments or questions directly to each article which the writers seem to respond to within a day or two.
So even though a subscription or book purchase probably won’t break your bank account, chances are you can get by with just these free tools. Keep an eye on other paid sites that offer something similar.
And finally, if you aren’t sure whether to follow the Chicago Manual of Style or APA Style or you aren’t finding a hard and fast answer, never feel like you’re in the wrong by following what you think is best for your readers. They’re the ones that matter. If it’s a more casual write-up, write like your readers speak. Write how you speak. Use grammar that you know and leave colons and “whom” at the door.
The great thing about language and grammar is that it’s constantly evolving along with its users. I mean, hell, if we take it back old school, is the contracted “have” in “You’ve got mail” even necessary? Nope, but it sure did catch on as an acceptable phrase.
1. The Chicago Manual of Style is an American English style guide followed by many publishing companies since 1906. www.chicagomanualofstyle.org
The Publication Manual of the American Psychological Association is the style guide adopted by many of the social and behavioral sciences first created in 1929. www.apastyle.org
Who to Keep in Mind When Writing
Short Answer: Your Audience
Better Answer: Everyone
If you ever took a course on writing, you know to define your audience beforehand and keep them in mind when writing. Questions like “Are they existing customers or potential clients?”, “Do they know their way around the product?”, and “Are you convincing them of something or providing instruction?” help you to create content that works for them.
But if you focus too much on a specific audience, your words could pigeonhole your product or leave room for misinterpretation.
So I say don’t write only for your audience. Write for the everyday person, for yourself, and for your company.
The Everyday Person
Even if you know the role of the reader, you probably don’t know how much experience they have with your product. Some could be a customer for years, others could be new to their job entirely. You don’t want to assume all readers are seasoned. By following these tips, not only will your intended audience understand you, but the new graduate your client just hired will be able to follow along.
Stay away from jargon.
I get it. Jargon is cool and often times easier to use. But if you use too much of it and never explain yourself, some readers might feel like they’re not in with the “in” crowd or just confused in general. And if they’re potential clients coming from a new market, this could turn them off enough to look elsewhere. Try to replace jargon with everyday words. If not, include a quick explanation of the term the first time you use it.
Slide in a reference list.
To write for your intended audience and the everyday person, the answer is reference lists. You don’t want to saturate your content with too much detail to accommodate the everyday reader – that’ll irritate your intended audience. What you can do, however, is slide a reference list in or add it to the side, so your less experienced readers can learn from it and your seasoned readers can skip it.
You and Your Company
Now that you know how to write for your readers, don’t forget to write for you and your company. It’s easy to focus on what’s right for the customer and put yourself before them, but it’s also important you do the following:
Cover your ass.
Writing content for your company is as much for the readers as a chance to cover your ass. If you leave out pertinent information, you can’t blame user error when something goes wrong. If you use vague words as a way to persuade potential customers, you may end up promising more than you plan. You don’t have to expose your faults, just make sure to point them in the right direction.
Feel confident in your writing.
The moment you try to sound like someone you aren’t, you lose your sense of self in your writing. Trying to sound too hip or too intelligent usually comes out like a mess. Readers read right through this, and your words end up sounding weak. Stay true to your voice and to your company. The confidence will show and help convince your readers.
You want your writing accessible. And you want it to work for you.
So write for the everyday person and yourself just as much as you write for the intended audience. If the person just clicking through websites can’t make sense out of the blurb on your About page or the installation manual under your Support page, then you’re probably turning away clients sooner than you thought.
How to Lighten Up Your Writing
In a world of taglines, Cliff Notes, and Adderall, it’s no surprise the attention span of readers is dwindling . So when creating content for your website or business documents, rather than mimic the style of Jane Eyre, keep your writing light.
Sounds simple, but if you grew up like me with teachers requiring minimum page lengths, it may not come easy. I would always fluff up word counts and try to sound sophisticated only to be left with a heavy writing style. When your writing is heavy, your readers gloss over and stumble over the content. And whether they skip words altogether or try relentlessly to get through them, the point you tried to make probably got lost.
To shed the word-weight, try this trick:
After you finish writing and completing the usual grammar and spellcheck, go back and try to cut each sentence in half. By that, I don’t mean delete all intro clauses or lengthy examples, although maybe you should. Instead, comb through each sentence and get rid of each word that just adds fluff. Here’s a few to get you started:
Words clogging up your sentence without furthering your point. They can include THAT, ALSO, JUST, IN ADDITION TO, THEN, CAN.
The word THAT is a huge culprit we don’t even realize we say. For example, I originally wrote “it’s no surprise that the average length of a reader’s attention continues to get shorter”. Instead I removed THAT along with a few other words, and what’s left? “It’s no surprise the average attention span of readers is dwindling.” The message remains the same.
Poor Tense Words
Words related to present progressive, past progressive, or future progressive tense. Look for verbs ending in –ING, the verb BE, and the word HAVE.
Instead of “Next, you are going to fill out this form,” say “Next, fill out this form.” Instead of “Last week, we were moving to the new office, and next week, we will be going to the annual conference,” say “Last week, we moved to the new office, and next week we head to the annual conference.” Instead of “We have been focused on hiring people that have just graduated college,” say, “We are focused on hiring new graduates.”
Words you think help clarify your point, but just get in the way. Look for those ending in –LY.
Instead of using an adverb to further describe a word, why not leave the word alone so it stands out or use a better word? For example, “Carefully examine each material,” sounds like you’re babying me through the steps. “Examine each material,” is much more direct and the focus is on “examine.”
Once you finish chopping up your word count, read your first draft again. Do you find yourself stumbling through it? Now read your new draft. Feels lighter, right? This isn’t to say you should never use the words above, but if you can remove them, and the sentence still conveys the same meaning, then delete away.
Like any workout, it may take a while to get rid of these words in the beginning, but soon you’ll be crossing them out as you write. They’ll feel heavy as you type. The effort of combing through each sentence is better than leaving that weight on your readers.
As Antoine de Saint-Exupéry (French writer, aristocrat, and aviator) once said:
“Perfection is achieved, not when there is nothing left to add, but when there is nothing left to take away.”
Even I can admit, when I first let loose on this post, my word count was up to 800, now it sits at a much lighter 610.
Why Your Wiki Needs a Wrangler
Back in the early 2000s (so let’s say a decade ago), the wiki trend emerged (think Wikipedia). Companies created wiki sites left and right, either internally for employees or externally for customers. And why not? It worked as a resource for everyone. People could collaborate and make changes to the content in a matter of clicks. And best of all, many of the wiki applications came FREE! Out of the over 43 wiki applications, about half are free, including the software Wikipedia runs on – MediaWiki.
So now it’s ten years later, and while social networks are the new trend, wikis are still commonplace. Partly because wikis involve a sort of social aspect (what with the collaboration and all) and partly because of how easy they are to use. The question is, though, what kind of shape are these wikis in now? Does the content make sense, and can readers find what they’re looking for? Or is it more a miscellany confusing the reader and leaving them dizzy from clicking?
If you have no one devoted to wrangling in the wiki content, then the answer is probably the latter.
A common example of this is software companies using a wiki to host their user documentation. The developers create the product and are then responsible for publishing its documentation to the wiki – which is a recipe for disaster.
Instead you need a writer devoted to the wiki, and here’s why:
So your developers can develop.
And by “developers” I mean the people asked to create content for the wiki IN ADDITION to creating products for the company. You don’t want your developers spending time pining over what words to use or if their words make sense. They should be spending that time innovating the product. AT MOST developers should send a brain dump of information over to the Wiki Wrangler so he or she can make sense out of it. With a brain dump, developers aren’t as worried about looking foolish with their grammar, so you tend to get more content out of them, and they tend to spend less time writing it up. A win-win. In the end, you get a wiki written in a single voice that users can follow.
To keep your content clean like a bonsai tree.
If having one person (or a small group of wranglers) edit all the content before it goes into a wiki is asking too much, at least have a Wiki Wrangler to regularly check over the published content. It becomes their job to cultivate the wiki like a bonsai tree, creating the wire frame for content to cleanly grow from, pruning the pages to keep the organization tight, and trimming content to make sure it doesn’t go off on tangents. The more cultivated a wiki is, the easier it is for users to quickly find what they’re looking for and the fewer clicks they’ll need to get there.
To give your users someone to vent to.
As someone who’s been the sole writer and wrangler for a software company’s wiki, I see this as a necessary evil. While answering emails from the user-base came be tedious, it can also be very beneficial to both the quality of the content and the user experience. Users appreciate knowing their questions/comments are read. And if one person is reading through the emails, it’s easier to find trends in the user experience. What topics are users getting hung up on? Where’s the pain point? All questions that can be answered when you have one person focused on the wiki.
Wiki Wranglers don’t always need to be full-time employees, though.
Just recently I did a project for a leading BPM software company that worked their way into the Leaders Quadrant of Gardner’s Magic Quadrant for BPM software. I did an inventory of all the pages they publish on their wiki documentation site and delivered a report of my findings.
I went through the content on each page and grouped the pages into four categories: Delete/Deprecate/Revamp/Condense. The Delete group were pages they could live without since the content was already elsewhere, the Deprecate group were pages they could stop worrying about because the feature was on track for deprecation, the Revamp group were pages that just needed to be cleaned up to match the Style Guide, and the Condense group were pages they should condense into broader pages.
See, the problem this company had was too many pages, which to me is the best kind of problem. They had the content to play with, they just needed to bring it all together so their users weren’t clicking all over the place and landing on pages with three lines of content they already knew about. Their wiki bonsai was in dire need of a wire frame and massive trimming.
By condensing their pages into broader topics, each topic page could work as a one-stop shop.
Users could search for a general term and get a broader topic page as the first result. Once they click on it, not only will they find the content they need (either through the Table of Contents or using Ctrl-F), but they are also free to discover the other content related to their query.
Through my inventory project, I was able to find about 115 pages that could be deleted and 443 pages that could be condensed down to about 40. In the end, I found an organized way for them to go from about 900 pages to 200 just by wrangling in the content they already had.
The thing to keep in mind is users don’t mind scrolling . . . it’s the clicking around that makes them crazy.
Get yourself a Wiki Wrangler, if not full-time, at least for a yearly review. Your users will thank you.