Archive for the ‘Technical Writing’ Category

How to Create Beautiful Content That People Love to Read

Thursday, March 5th, 2015

We all want to create beautiful content but somehow we can’t get our heads wrapped around it. You don’t need to be Shakespeare to write great content. All you need to do is give your reader useful information and let quality reign!

I’d like to offer some suggestions on how to create excellent content that your audience will love to read.

  • Avoid spelling misstakes – see how bad this looks? Typos and grammatical mistakes would lower the quality of your content. It would be a shame to work for hours and hours to write fantastic content only to find – after you published it – an ugly typo or glaring grammatical mistake. Worst yet, your audience finds it before you do.
  • Avoid using texting language like “cuz” instead of “because” or “u” instead of “you” otherwise you would appear like someone trying to act too young for their age.
  • Don’t use quotes unnecessarily. I’ve seen content where technical jargon is quoted all over the place and it looks really messy. You should only use quotes when you’re quoting someone.
  • Make sure you use the correct word for the context. The one wrongly used word that drives me mad the most is when people use the word “loose” instead of “lose” as in “I’m about to loose it!” Lose the loose when you’re about to lose it!
  • DON’T USE ALL CAPS BECAUSE IT LOOKS LIKE YOU’RE SHOUTING. No one likes to be shouted at so don’t shout at your reader. Besides, it’s really hard to read.
  • Don’t use unnecessary bolding because this also looks like you’re shouting. Too much bolding makes your text look loud and garish. Your reader would get a headache and leave your content in a New York minute. Only use bolding to emphasize important information.
  • Don’t use unnecessary italics otherwise your text will be hard to read. Too much italics could slow down and frustrate your reader. If you’re like me, you would get impatient and – yes you guessed it – look for the nearest exit. Use italics for titles or file names.
  • Be consistent and don’t use too many different fonts and bullet styles. Several years ago, I had to revamp this manual because not only was it a complete mess, it also had about 10 different font styles. My brain raced every time I had to go through this content. Added to this chaos were several different styles for the bullet points – dots, arrows, check marks and dashes. It took me weeks to get this madness under control so the average human can digest the material. Don’t do this to your reader.
  • Always pluralize correctly. Don’t pluralize with a “z” instead of an “s” as in “shoez”, “dreamz”, “accentz” or “namez” otherwise you would risk looking unprofessional if done in the wrong context. I’ve seen this pluralization in business names but I can see this fad dying out really quickly.
  • Lose the corporate speak – fast! There is nothing more annoying that trying to decipher corporate speak nonsense when I’m reading something important. Yesterday, I was reading an article (won’t say where) that discussed the US “normalizing relations” with Cuba. Oh for crying out loud! Couldn’t they say “make peace with Cuba” or “cooperate with Cuba” or something like that? I know my version is not perfect but at least the reader would get an idea of the meaning.

These are a few of the many ways you can create excellent content that your audience loves to read. If you remember just these few suggestions, you’ll be well on your way!

If you got other tips to add, let me know in the comments.

How to Write an Effective Company Policy

Thursday, December 4th, 2014

Are you struggling to write your company’s policy? If so, here are a few ideas to get you started.

You can organize your policy as follows:

Purpose – Explain what the policy is about and why your employees should follow the policy. To come up with this information, ask yourself “What behavior am I trying to teach?” or “What behavior am I trying to change?” or “What behavior am I trying to stop?”. For example, you may have implemented your Dress Code policy to get your employees to wear proper business attire to project a more professional image of your company.

Scope – Indicate who should follow the policy. Your Dress Code policy may apply only to your Sales and Marketing staff who deal with your customers face to face.

Out of Scope – Indicate who the policy does not apply to. Your Dress Code policy may not apply to back office staff who don’t deal with customers.

Effective Date – Tell your employees when the policy comes into effect. If your policy is effective today, you can say effective immediately.

Responsibilities – Explain who is responsible for what. Ask yourself questions like “Who will make sure that everyone follows the policy?” or “Who will enforce it?” You can also explain the levels of enforcement such as a verbal warning for a first offence, written warning for a second offence, and demotion or dismissal for a third offence (depending on how serious the offence is).

Policy Statements – List all the regulations, requirements or the do’s and don’ts. This is the main part of your policy. It can be one to several pages, depending on how complex your policy is. For your Dress Code policy, you can list what is acceptable or unacceptable business attire.

Other Sections You Can Include

Background – Explain the history or events that led to the creation of your policy. Maybe you’re implementing a Dress Code policy because one of your biggest customers complained about your staff dressing unprofessionally.

Definitions – Spell out acronyms that are unique to your company, and explain ambiguous terms and concepts.

Distribution – Specify who gets a copy of the policy.

Contacts – Tell your employees who to contact for further information.

Review and Revision – Specify how often the policy is reviewed, who reviews it, and who authorizes the policy. You also can tell your employees that your company reserves the right to rescind or amend the policy at any time.

So that’s it in a nutshell. With these ideas in mind, writing a policy is not so bad. The key is to organize the information so that your employees can follow it easily.

What was your experience in writing your company’s policy? Please share them in the comments.

How to Write a Procedure That People Can Follow Easily

Tuesday, November 25th, 2014

If you want your users to follow your procedure, you should make it as easy as following their favourite recipe.

The next time you’re cooking, take a look at the recipe. You’ll notice it has three parts:

  • List of ingredients – Tells you what you need to start the recipe
  • Steps – Explains step by step how to prepare the recipe
  • Number of servings – Tells you how many people you can serve

Your procedure can have three parts as well:

Before You Begin: Like the list of ingredients in the recipe, this part tells your users what they need before starting the procedure. Do they need prior knowledge before starting the procedure? Do they need certain materials? Or, do they need to do something to prepare?

Steps: This part tells your users what they need to do first, then second, and so on. Tell them what happens as they go along so that they know if did the right thing. For example, if you’re explaining how to use an application, you can show the windows that appear at critical steps so your users will know they’re in the right place.

Result: Like the number of servings, this part tells your users what to expect. If you tell your users what happens after they perform the procedure, they can check if the right thing happened.

Other Useful Parts You Can Include at the Beginning

Audience: You can tell your users who the procedure is written for. For example, if you indicate which procedures are for Level  1 Support, Level 2 Support and so on, it will save your staff time and frustration from following the wrong procedure.

Purpose: When you tell your users why they need to follow the procedure, it will make more sense to them. They will learn it more quickly and  make fewer mistakes.

But what if my procedure is complex and involves more than one role?

This question is easy to answer. You can have a role table that lists the steps for each role, and it will look something like this:

Role Action
1 Level 1 Support Get the following information from your customer: name, telephone number, workstation number and a description of the problem they are experiencing.
2 Level 2 Support Open the ticket from the Remedy application. If you resolve it, close the ticket. If not, send the ticket to Level 3 Support.
3 Level 3 Support Open the ticket from the Remedy application. If you resolve it, close the ticket. If not, send it to the Senior Developer.

Test Your Procedure

If you want to make sure that your users understand the procedure, have one or two users follow it in front of either you or someone else who understands it. Note where they make their mistakes and ask yourself questions such as: Were all the steps worded properly? Are any steps missing? Is it self-explanatory or clearly explained what happens after each step?

If the users who tested your procedures can follow it, chances are, the other users will be able to follow it too.

A Good Procedure is an Investment

Not all procedures are as easy as a recipe. In fact, some procedures are long and complex.

However, if you take the time to write good procedures for your staff, you will save time and money from training and support. And things will run much more smoothly because your staff will be more productive.

What are your thoughts? How can you tell if a procedure is good or bad? Please share them in the comments.

Active Voice Versus Passive Voice

Friday, October 31st, 2014

The difference between the active voice and passive voice is easy to understand.

In the active voice, the subject of the sentence performs the action. The active voice answers the question “Who or what performed the action?”. Examples are: “John dropped the ball.” and “The dog barked at the cat.”

In the passive voice, the subject receives the action. The passive voice answers the question “What action was done by whom?” or “What action was done by what?”. Examples are: “The ball was dropped by John.” and “The cat was bitten by the dog.”

Why use the active voice

  • It emphasizes who or what performed the action.
  • Your reader grasps the meaning more quickly. This is important especially if your reader is using your content to do something urgent.
  • Your content is more powerful and direct, which keeps the reader interested.

When to use the passive voice

  • It is useful if you want to emphasize the receiver rather than the doer of the action.
  • You use the passive voice if you do not know who is performing the action.
  • You can use it to protect someone’s name from being released or to be tactful, for example, “Mistakes were not noticed.”

What are your thoughts on the active versus the passive voice? Please share them in the comments.

Know Your Audience

Thursday, December 13th, 2012

Whether you’re writing a book, blog, article, newsletter, web content or ebook, you need to know your audience.

The saying “different strokes for different folks” applies to plain language. What is plain language to one audience may not be plain language for another.

It’s impossible to know every aspect about your audience because there are too many factors to consider. However, it’s vital that you understand your audience as much as you can. Ask yourself the questions like:

  • Who is your audience?
  • What do they know about your topic? Are they beginners, experts or somewhere in between?
  • What is their age group and gender?
  • What is their culture?
  • What is their level of education and skills?
  • What is their occupation?
  • How will they access your content (print, online, mobile device)?
  • Will they access your content from work, home, or while travelling?
  • What information do they need? Do you teach to teach them? Inform them? Entertain them? Persuade them? Train them?
  • Does your audience have unique needs or interests?

You can get answers to these questions by talking to your audience directly in one and one meetings or in focus groups. You can also talk to experts – like subject matter experts, sales and marketing staff, and customer representatives – who know your audience well.

Knowing your audience is an essential first step to writing content that meets their needs. You avoid the embarrassing problem of writing content that is not relevant to them and the expense – in time and money – of having to rewrite the content.

So, what about you? How do you get to know your audience? Please share your thoughts in the comments.