One thing about hiring experts – we’re thorough. We often identify changes, beyond the software, that could improve the content. Most are minor, such as updating titles to make sure that they accurately capture the user tasks or identifying wording consistency issues. But, sometimes we uncover broader issues, such as content that doesn’t address user needs or content that is missing important information. These changes take longer to address and can come as a surprise to the company, especially if they have been keeping up with smaller updates.

Here are a few reasons why a company’s documentation might not be as complete as they think that it is.

Starting with information meant for a different audience

Software projects are often under tight timelines and documentation updates are usually the last thing on the to-do list. Pressed for time, it’s easy to copy the relevant information from other project documents and make the basic changes. Some changes are easy to spot – such as turning descriptive paragraphs into numbered steps. But, others aren’t as obvious. For example, it’s harder to break away from the existing structure to look at it from the user’s perspective. So, even if the copied text is edited to make it more user-facing, the structure of the original source still dominates. Often, the source information doesn’t follow the order that users would complete the tasks in. Without seeing tasks in their natural order, it’s harder to spot what information might be missing. Other times, a single task is created, rather than splitting information into multiple tasks. Because there is so much information there, it’s hard to see what isn’t there.

Not looking at all the existing documentation

Incomplete updates are also a result of the iterative nature of software development. Because software updates usually focus on a specific part of the software, it’s tempting to narrow the focus of the documentation changes to the immediately impacted topics. Individually, the targeted updates seem reasonable and complete. But, over time, these isolated changes lead to a fragmented or inconsistent guide. By ignoring the larger documentation piece, isolated updates can overlook or exclude related information that could help users accomplish tasks more easily.

Without looking at the complete task flow in a document, isolated updates can also lead to odd workflows that jump around and confuse users. They can lead to procedures that are near-duplicates of one another, without enough information to distinguish between them. This duplication can mislead users – they don’t know which task to follow and ultimately might have them looking for information elsewhere.

Those iterative updates might be done by employees who specialize in a particular aspect of the software – and who focus on a particular content deliverable. No one is looking at the entire content set. Someone updating the user guide might not realize that there are FAQs that address the same issue. Again, duplication abounds and users are confused.

How does your documentation stack up?

Before a company updates their documentation to add new or changed features, they should take a step back and think about whether the current content addresses their users’ needs and whether it is as complete as it can be. If it’s not, they might be creating the documentation equivalent of a Jenga® tower: a large pile of information with tiny holes in it that creates an unreliable base for their users.

Because we look at documentation with fresh eyes, we are more likely to spot issues. If constraints don’t allow all changes to be made at once, we can recommend the most important ones to shore up your documentation and support your users. With our years of documentation expertise, the writers at Spark can fill those holes and make sure that you can continue building your documentation on a stable base.

As smartphones got smaller, the boxes got smaller too. As they became more ingrained into our daily routines, they also came with more accessories to help us out. All of this left less and less room for user documentation. Often, we had to think outside of the box to figure out how to fit everything inside the box.

The most obvious way to reduce the size of printed documentation is to reduce the amount of information in it. For both environmental and space reasons, we moved much of the smartphone documentation online. But, there were some things that we couldn’t move, such as information on where the power button was, or what gestures users needed to know to navigate the user interface and set up the phone – not to mention how to find all the information that we had removed from the printed documentation!

But, what do you do if you’ve removed all the information that you think you can and you’re still struggling to fit your documentation into a physical package? Here are a few other ways to shrink your printed documentation without impacting its usability:

• Use thinner paper. When box space is measured to tenths of a millimetre, shrinking the thickness of each page can make a difference when you add up the pages. Keep in mind that the paper still needs to be thick enough so there’s no ink bleed from one side of the paper to the other. The documentation isn’t helpful if users can’t read it.
• Reduce the font size. There is a limit to how low you can go – in limbo and in font size. But, font size is often something that you can play with. Keep your audience in mind, as products aimed at younger audiences can generally squeak by with smaller fonts than those aimed at an aging population. If you’re translating the documentation, you might not be able to reduce the font size for some languages without impacting the readability of the characters.
• Use narrower margins. If you have short paragraphs or steps, you might be able to get away with slightly smaller side margins. But, there is a limit to how tightly you can pack in the text. People need white space around the text – both between the lines and at the sides – to comfortably read it. With short paragraphs, however, the internal white space might balance out the decreased space in the margins.
• Replace text with graphics. Unlike the old adage says, you can’t often replace 1000 words with just one picture. But, you can condense short bits of information into one graphic to save space. In most cases, callouts or tables are easier for users to scan and find the information they need, rather than long paragraphs of text.
• Look at the whole package. This is where you start to think outside of the box – and the documentation. Can some information go somewhere else? For example, is there empty space on the packaging where you can put support information? Is information duplicated? If it’s on the packaging and in the documentation, can you remove it from one? Can you replace paper with another format? In our case, the smartphones shipped with blank clings on the screen and the back of the device. By moving some information out of the documentation and onto those clings, we could make better use of the space. And, better yet, the information was more visible to users.
• Take another look at the information. It never hurts to take a second (or third) pass at your content to make sure that it really is as streamlined as it can be. A good editor can help you with that task. It’s easy to get into the habit of carrying forward information because it’s always been there, without considering whether it is still necessary. A fresh set of eyes can help assess the need for content. For example, new features or emerging technology might necessitate a more detailed explanation at first. But, as it becomes mainstream, you can likely reduce that additional contextual information. Or you might be able to remove it entirely.
• The Three Cs: When you know what content needs to be included, it’s time to take a review how the content is written. Clarity, consistency, and conciseness are rules that every technical writer needs to live by. When you are working with tight spaces, they are even more important. Are there ways to tighten up the text? Have you applied plain language principles? Can you use fewer words to express the same thought?

As you can see, there are many ways to reduce the size of your documentation without reducing its usability. You might even find that making a few changes to reduce space improves the overall readability of your documentation.

If you need help fitting information into a printed format, or figuring out what to keep in the box and what to do with the rest, give Spark a call. We can help you find a solution to your space problems.

It’s all about perspective

The best documentation addresses what users are trying to learn, not what the writer is trying to tell them to learn. Many developer and marketing documents tend to focus on what the writer wants the reader to know. We can’t fault them: people tend to write about what they know. Developers know how they’ve coded the user interface, so development documents tend to outline the UI elements and their options. Marketing teams want their product to sound better than the competitor, so their documents list flashy features and impressive statistics. But, both often miss out on why the user interacts with the documentation. Users don’t want to know what settings are on a screen. They want to know why they need to use those settings. And that list of flashy features loses its shine if users don’t know why those features are so great. When thinking about user documentation, it’s important to understand the user’s goal in reading the documentation.

The key is thinking about why, not just what or how

To get to the user’s goal, we ask questions. The first two are “What does this do?” and “How do you use it?” While it might seem like that’s all the information that you need, it’s missing one important piece. The what and how don’t help users without also asking the why.

If I told you how to change your phone settings so that applications closed after a set period of inactivity, what would be your incentive to use this feature? It might take you longer to open the app the next time you wanted to use it. That doesn’t sound like a useful feature and you have no reason to use it. But, what if I told you that closing your apps made your phone battery to last longer? There’s your incentive. There’s the why.

By asking questions, we find the why that users are looking for. We also sometimes uncover awkward workflows that come from forgetting the why. For example, you might have two teams who are working on two separate, but related, features, each with its own settings screen. If you focus only on the how of changing the settings for each feature, it might not be obvious if users must make changes on one screen before making changes the other. If the task done frequently, switching back and forth between the screens isn’t the best solution. Asking why a user is changing the settings reveals that it is more effective to have the settings on one screen, regardless of which team coded the features.

Writing is about anticipating what users want to know

It’s easier to write about what a product or feature does. But, it’s more effective to write about why someone would use the documentation for that product or feature. By focusing on why, you are more likely to meet their needs. And, if you can’t meet their needs, they’ll go somewhere else that can.

If you aren’t sure if your documentation is giving users what they need, the writers at Spark can help you find the right focus.

Have no fear! There are several free tools that you can use to make sure that small mistakes don’t drag down your writing when you’re crunched for time.

For this post, I considered some common consequences of quick writing – spelling and grammar mistakes, passive voice, and poor readability – and looked at the pros and cons of Microsoft Word, Grammarly, and Hemingway Editor.

A few caveats: I haven’t tried the paid versions of Grammarly or Hemingway Editor since this is about free tools, so all comments refer to the free versions. Word isn’t technically free, but since most companies already have a license for Word, there’s no additional cost to use it.

Microsoft Word

You’re probably already familiar with Word. It checks spelling as you type, or you can run the spelling and grammar checker as a separate tool. It autocorrects common typos, such as teh or adn, and you can add your own typos to the autocorrect list.

What many don’t know is that Word also has a feature that uses standard readability calculations to check how readable your text is. By looking at the length and number of words and sentences, Word can give you an idea of how easy your text is to read.

To turn on readability statistics, go to File > Options > Proofing. In the When correcting spelling and grammar in Word section, select the Show readability statistics check box.

To check your text, on the Review tab, click Spelling & Grammar. After the spelling and grammar checker runs, Word shows the readability summary.

In the Averages section, look at the Words per Sentence metric. Shorter sentences are easier to read and understand, so try to keep the number lower. An average of about 15 words or less is a reasonable length.

In the Readability section, look at the Flesch Reading Ease and Flesch-Kincaid Grade level. These show how complex your words and sentences are. A higher reading ease number and lower grade level indicate that more people will be able to understand your message. I usually aim for a reading ease above 50 and a grade level of 9 or lower.

Older versions of Word showed the number of sentences that used passive voice; newer versions don’t. If your version of Word shows it, aim for zero. Passive voice can obscure the meaning of a sentence, so it’s better if you can use active voice.

Tip: If you are having a hard time getting the Flesch Reading Ease number up or the Flesch-Kincaid Grade Level down, select and run the spelling and grammar tool on a few paragraphs at a time to figure out which paragraphs need special attention.

Grammarly

To use Grammarly, create a free account at www.grammarly.com. After you create your account, you can use the online editor or download the desktop application. You can integrate Grammarly into Microsoft Office and your Outlook email client. If you use Chrome, you can also add the Grammarly extension.

Although the premium version offers more features, Grammarly’s free version is still surprisingly robust. It looks for spelling, grammar, and punctuation errors and offers suggested changes. It also looks at sentence structure and common style errors.

Hemingway Editor

You can use the Hemingway Editor online for free at www.hemingwayapp.com or download a paid desktop version.

To use the online version, paste or type your text into their editor. It marks up the text as you go, flagging spelling errors, sentences that use passive voice or adverbs, and long sentences.

Which is the best?

None of these tools are foolproof. Word’s readability statistics are useful as an overview, but they don’t help your fix errors. Hemingway Editor flags sentences that use passive voice and complex phrases, but it can be finicky to use. Grammarly’s integrated features are handy, but I still ignore some of its “errors.”

This list of tools isn’t exhaustive – they are just three of the more common ones that I’ve tried. So, if none of these work for you, poke around and try something else. Use whatever you feel comfortable using!

If you can’t find something that works for you, or you have documents that need more in-depth review, the keen-eyed human writers at Spark are always here to help!

The content gets a bad rap – it has a reputation for being dense and confusing, with its complicated and detailed language. That language seems necessary – insurance paperwork, for example, should be specific about what is covered. But, believe it or not, even this content can be complete without being complicated.

Today is International Plain Language Day. For almost 30 years, the plain language movement has championed clear communication using clear language. The goal is to get your message across the first time that it is read. It doesn’t mean that you need to “dumb down” your content, but that you tailor your content to suit your audience.

Plain language has some obvious benefits. If users understand your content the first time that they read it, it saves them time, reduces their frustration, and builds their trust. You can avoid misunderstandings, errors, and, even costly customer support calls.

Where do you begin? Here are six strategies that you can use to apply plain language to your content:

• Understand your audience: Ask some basic questions to understand who your audience is and what they know.
• Organize your content: Focus on what’s important to the audience and omit what isn’t necessary.
• Develop your content: Keep paragraphs to a single idea and use short sentences where you can.
• Consider your tone: Be aware of the implied tone in your writing. Make sure it’s what you want.
• Consistency, clarity, and conciseness: Revise your content. Look for inconsistent wording, eliminate unnecessary words, and use words familiar to your audience.
• Use the active voice: Brush up on the difference between passive and active voice. Use the active voice when you can.

Converting your content to plain language can take planning, when you consider how much content you have. Everything from website content to social media posts to product collateral can benefit from plain language. You can phase it in over time, but you risk giving users a disjointed message. Or, you can try to time it with a particular event – a product launch or refresh, for example. That approach is better for the user, but puts a lot of pressure on writing resources.

At Spark, we’re passionate about plain language and can bring out the best in your content. With our knowledge and experience, we can take complicated consumer communications and apply these plain language principles. The end result is clear, complete content that readers can understand – without the extra complications.

We all use them. Most of us use them correctly. Some have embarrassing mishaps. LOL-speak is easy to type and efficient at getting the meaning across, provided you are fluent. Abbreviated text grew out of necessity because of the teeny-screens on early gen cell phones. But, with smartphones and predictive text, aside from Twitter’s character limit, what’s the need*? Even though we might save money on our data plans and time spent typing, what is the true cost?

LOL-speak is meant to speed up the act of writing and relies on the reader’s ability to decipher the message. It generally works pretty well to pepper your writing with shorthand, but it is easy to lose reading comprehension when sentences consist of more abbreviations than not. Readers must struggle through the message and its meaning is lost. Realistically, LOL-speak will never die, but my beef is not really with the abbreviations. My concern is with its impact to society as a whole. What happens when our communications are reduced a string of barely comprehensible letters and numbers, sorely lacking in punctuation? Ask any writer what makes a good writer. They’ll tell you that it’s reading – reading everything, reading often. It is how we learn basic sentence structure, proper punctuation, and how to convey meaning. Reading imparts grammar wisdom more than any classroom lesson can. It’s actually quite beautiful how much we learn from reading without even realizing it.

Society moves at a lightning pace and people who take the time to read and absorb the likes of Shakespeare, Wilde, Orwell, Austen, Atwood, and Ondaatje are becoming increasingly rare. For most young people, reading is a chore forced upon them, and they are too busy hating their homework to appreciate what they are reading; that’s nothing new. But if you are constantly faced with incorrect punctuation in social media, online, and restaurant signage and menus (Entre’s), it is easy to become confused on what’s right. The result is no matter how many times you Google how to use an apostrophe, it doesn’t stick if you don’t see correct examples every day.

Let’s take that example – the apostrophe. A very small portion of the English-speaking population know how to properly use this punctuation mark. I’m willing to bet that those under the age of 30 who do know how to use it correctly are either ESL (who learned grammar to learn the language) or they are true word nerds. The more people see an improperly-place apostrophe, the more confused they are about how to use it properly, and they end up mimicking what they see. And often what they see is wrong. Misuse is now so common, I recently saw it in our local paper – and worse, on communications coming home from my child’s school. (Quick grammar lesson: An apostrophe does not make a plural. More than one cat = cats, not cat’s. An apostrophe is there to show possession. The cat has kittens = The cat’s kittens. Of course, that’s thrown for a loop when considering “its” and “it’s.” But, that’s actually pretty simple, too, because “it’s” is a contraction for “it is.” It is raining = It’s raining. “Its” is used for possessive. Leaves are falling from the tree = The tree is losing its leaves. If you can replace “its” with “his” or “her”, you’re using it correctly. Confused? Check out the Oatmeal for a flow chart. )

Sadly, I’ve almost learned to accept apostrophe abuse. Almost. What really horrifies me now is the complete lack of punctuation. Punctuation isn’t optional. It’s required for reading comprehension. The misplaced apostrophe, while cringe-worthy, is easy enough to parse. But, missing commas can completely change the meaning of sentences.

Take, for example, the simple phrases “Let’s eat grandma!” and “Let’s eat, grandma!” Those are two totally different sentences – one with a rather extreme and cannibalistic outcome.

By now, you probably think that I have turned into that fuddy-duddy who yells at kids to get off my lawn. I did say it is a divisive issue. Does it only bug me because I make my living providing clear, crisp, and concise content for my clients?** Maybe. But, hopefully, now that I’ve brought it to your attention, you’ll start to see more and more examples of missing or incorrect punctuation. Not just in social media, but legitimate news sites, magazines, or Buzzfeed articles. You might even notice that you aren’t using periods in your text and IM conversations. Sending the message has replaced end punctuation in many sentences. Ben Clair explains what happened to the period in this article in the New Republic.)

Ask yourself, if this is what we are doing to the English language now, what will we be doing in 30 years? Does it matter? Do we accept the changes as evolution and teach our kids how to use emojis to convey meaning? Or do we do our best to make our kids into readers and teach them to recognize a really great sentence? Will the English language be something else in the future?

Luckily, there are still a few pro-punctuation proponents out there who can make sure your comma placement and apostrophe use is spot on. Send an email to Spark Content to see if the grammar in your customer-facing content changes your meaning. We love this stuff!

* Threaded SMS makes the SMS 160 character limit a non-issue.

** Ahh, alliteration! See? Grammar can be fun.

We clarify and clean up

We’re writers. It’s our thing, and we’re pretty good at it (if we do say so ourselves.) Writing isn’t just putting words to paper. It’s finding the right words to use and creating a flow that’s easy to follow. People less familiar with writing principles tend to put as much information as they can into a document to try to help users. But what seems helpful to add can ultimately hold users back.

We’re skilled at taking technical content and making it easier to read. Have a manual that feels more like a medical textbook? We can streamline it to a more manageable size. We cut through the jargon and unintentional fluff to focus on the task at hand. Your users get the answers that they need as quickly as possible.

We look at the whole picture

We call ourselves content developers for a reason. We don’t look just at the specific changes that need to be made. We consider how those changes affect your company’s broader content set. For example, can changes help offset your customer support needs? How do they align with your marketing materials? If your employees focus on one area of your business, they might not realize that making changes can impact other areas. We can make sure that the impact is positive.

We also think about translation, legal requirements, and print needs. So, when those questions come up, we already have answers for you.

We bring an outside perspective

An outside perspective means that we step back and look at the content with fresh eyes. For example, the feature that took the longest to design or code might be the most important to your project team, but it isn’t always the most important to your users. Your employees might not even realize that they are attached to certain features after their trials and tribulations with them throughout a project. We have the experience to look at all of the content objectively and align it to what your users need.

Our unique perspective also means that we’re away from the technical details – just like your customers. We ask questions about what we don’t understand, which are probably the same things that your users don’t understand. We have a good perspective on the kind of information and level of detail that a user is looking for.

We also bring with us our years of experience on other content. You benefit from the times we reworked content to fit a smaller box size or developed online help for mobile applications. Our content experience can work for you.

We make your business our business

The obvious decision of using an engineer, developer, or marketing team member to write content isn’t so obvious when you look at what a contractor can bring. Your employee might know your business already, but we make it our goal to learn your business quickly. We know how to write about products, how to get to the heart of your message, how to make sure that the message compliments and aligns with your existing content, and how to make sure that it delivers what your customers need.

Make Spark Content your content development team. With our expertise, we look at the whole picture to polish your content. At Spark, we’ve got content covered.