Author Archives: lloydikus

Tutorial Writing: How to Connect with Your Readers

Tutorials are created every day.  Anyone who has spent any time in the vast universe that is the Internet knows that online tutorials are not scarce.  They can be found on virtually any topic.  There are tutorials on everything from cooking, to gardening, to raising children, to using the latest software, to fixing the latest problem afflicting your family car.  It seems that nearly every Internet user has searched for a tutorial to help them solve a problem.

With a seemingly unending supply of tutorials on a seemingly unending array of subjects, how do certain tutorials stand out?  What sets the tutorial that drives traffic to a website apart from one that simply lies dormant in the hustle and bustle of modern cyberspace?

It is a well-known fact in online communities that having effective tutorials is a great tool for driving traffic to a website.  Some online resources estimate that having one successful and well-written tutorial can do more to drive traffic to a site than more than 20 other articles combined.  Tutorials provide value because they teach something valuable.  Their shelf life is longer than other content because they are used over and over, sometimes for years.

When reading this you may be thinking about a tutorial you have attempted to write or one you are writing.  You may be evaluating what you have done right and what you may have done wrong.  How much traffic has that tutorial produced?  Have you gotten feedback from your readers?  Was the way you wrote your tutorial clear and did it make sense to the reader?  Do you have a plan in place for keeping your tutorial up to date? Do you continue to interact with your readers?

The purpose of this chapter will be to answer some of these questions.  By using the 10 tips for writing successful tutorials addressed below, you will be able to write tutorials that stand out online.  By providing readers with the most powerful and value-packed tutorials possible, you will ensure that readers will understand and gain value from your writing.  By making your tutorials as value-packed as possible, you will establish yourself as a respected resource online.

So let’s get to it. We will start with the first and perhaps most important decision you will make when preparing a tutorial…

Choosing a Topic

When starting a new venture, a formal business plan is crucial.   A business plan evaluates the market for a product or service.  Is there a demand for the product or service?  Is the market saturated with other similar products and services?

Just as in the scenario of a new business entering an unknown or new market, new tutorials are entering a busy virtual market.    It is unbelievably important to know how you fit into this space.  You have to determine if there is a real need for the information you will provide.

A good way to determine if there is a need for your topic is to look for the topic yourself.  Go online and perform Google searches on terms you think people looking for your topic would search for.  It is a good idea to search a variety of terms that could be used to search for your topic.  If needed pick up a thesaurus and find similar words to the ones you have come up with.   You may find a lot of information already out there on your topic, but don’t give up.  Read the actual tutorials and determine if the tutorials are valuable.  There may be a lot of information about the topic, if this information isn’t good or clear then you could provide a superior tutorial to those currently available.

Another important thing to consider when choosing a topic is if you know enough about the topic to make your tutorial useful.  Readers will be able to determine very quickly how much you know about your subject.  If you can’t portray yourself as an expert on the topic, readers will quickly lose interest or realize they are not gaining valuable information.

Defining Your Audience

I attended a business meeting the other day.  As usual the appointment was set up in my Microsoft Outlook calendar with a topic of training on a new system that my company was implementing.  Not being familiar with the system and also having a few new employees that needed training on the system, I gladly accepted the appointment.

The morning of the appointment arrived.  No sooner had the meeting begun than I started to realize the oddity of what was being presented.  On the other side of the room there were a few gentlemen that I did not recognize.  The presenter only addressed them and seemed to be pitching the system to them.  Little training was going on.  For two hours we sat as the presenter told about our systems and pitched the systems to another group within our company.  The purpose of the meeting was not training at all!  Needless to say, we felt this was a huge waste of our time.

This example demonstrates the importance of knowing your audience.  It is important to know the demographics of your audience and their competency level in your topic.  It is also crucial to know information about the online locations your tutorials will be posted.  If you aren’t careful you can include a lot of things in your tutorial that your audience simply doesn’t care about.

If you are creating a tutorial about how to use a software program making the tutorial too complicated and using advanced terms will confuse beginner-level users.  On the other hand, if you make the tutorial too simple for advanced users you will bore them and they will get the information elsewhere.

Something else to consider is where your tutorial will be posted.  If the tutorial will be placed on a blog with a large community of experts, you will want to write a tutorial geared toward advanced users.  To ensure you are writing to all user capabilities, provide a couple of different versions of your tutorial.  Give the users an option of which version they would like to use – simple or advanced.

Organizing Your Tutorial

Now that we have a great topic and we know whom we are writing to, we are ready to get started, right?  Not so fast.  There is one more thing you should think about.  How is your tutorial going to be organized?  A well thought out organization will make more sense, the content will shine through, and will be more valuable.

If your tutorial is lengthy, you will want to break it up into sensible sections.  A good way to do this is to separate each section onto a separate Web page.  By using next and back buttons to navigate between sections, you can provide bite-sized pieces to your readers.

There are four things to remember when breaking tutorials up into sections.  First, make your section breaks in logical places.  Try not to break to a new section mid-thought.  Second, consider that some readers may want a beginning to end tutorial on one page, regardless of length.  Including a one-page version of your tutorial will be useful to some readers.

Another thing to consider is a table of contents.  Letting your readers know where they are at in the tutorial, where they are going, and places they can go is useful.  This will also enable readers to better locate specific subjects they are looking for within your tutorial.

Finally, come up with a standard on how you are going to incorporate things like lists and other components, such as quick tips or definitions, to break things down into simple steps.

Writing an Introduction

OK now we are ready to start writing.  One of the most important things you will do to draw people to your tutorial is to write a good, compelling and interesting introduction.  This is one of the first things that readers will see on your tutorial.  This is where they will answer questions they have: Will this tutorial provide me the information I am looking for?  Will it be professionally written?  Will the tutorial make sense?

Your introduction should fulfill several requirements.  Your introduction should clearly state the purpose and objective of your tutorial.  What are you going to teach the reader?  What are some of the techniques that will be used to teach the objectives?  Your introduction should also include any prerequisite skills that the reader should have before beginning the tutorial.  When creating tutorials where readers will be following steps in software programs, a list of software or plugins required to follow along is helpful. If certain versions of software are required, these should also be listed in the introduction or somewhere else toward the top of the page.

Making Your Tutorial Clear and Concise

The best tip for making your tutorial clear and concise is to remember the objective of your tutorial.  The objective of all tutorials should be to teach your reader.  A lot of tutorial writers will tell you that no matter the subject or the audience, you should always write at a third-grade reading level.  This isn’t to say that the contents of your tutorial will not be valuable to an advanced reader.  The suggestion is to use language that would be understandable to most everyone who reads it.  Avoid using big words and complicated sentences that some readers may have a hard time understanding.  You want to make it easy to read so that the content shows through.

Something else you will want to do when outlining steps in your tutorial and having the reader perform certain actions is to explain why they are doing it.  By answering the “why,” the reader will learn even more and will have a deeper understanding of the steps in your tutorial.  One thing you do not want to do is confuse and frustrate your reader.  What the tutorial is aiming to accomplish should be clear to anyone who uses it.

Having clear, concise, simple information does not necessarily mean you have a lack of information.  In fact, having too much information is better than having too little.  If there is a question of whether to include a piece of information, it is always better to err on the side of too much information.  Making that information simple to follow, clear, and concise is the thing that really matters.

Consider the following two sentences:Sentence 1:   Select the button in the upper left of the screen.Sentence 2:    Click the green Processbutton in the upper left-hand corner of the screen.Note: When clicked, the Process button will process what you have entered into your table at the current time

Sentence one, while short, does not provide a lot of useful information.  The description, “the button” does not adequately describe where the user is meant to click.  By providing a color and naming the button, as in sentence two, the reader should know exactly where to click.  Also by providing a small note the reader knows what the button does and why they are performing the action.

Using Images

The saying “a picture is worth a thousand words” surely holds true in tutorial writing.  Images provide clarity and explanation to your tutorial.  They will help to simplify things for the reader and, if used correctly, act as a valuable tool in teaching.

You should always place some kind of image toward the top of your tutorial, preferably before or after your introduction.  The image that you use will depend largely on what your tutorial is about.  In the majority of instances, your tutorial will produce an end product.  An image of the end product of your tutorial is a great thing to include as this first image.  If the user is doing something in PhotoShop, place the finished image at the top.  If the user is cooking something, place an appetizing photo of the masterpiece near the top.  You get the idea.

Consider placing watermarks over some of your images.  This will help to protect images  you may own.  Reviews are mixed on this practice.  Some tutorial writers will tell you to watermark all of your images and some will tell you to watermark only a few.  When watermarking only a few images, it is usually suggested to watermark those near the beginning and end of your tutorial.

Probably the most common and valuable use of images is using them to explain steps in a software program.  Many modern programs are hard to understand with multiple menus, toolbars, buttons, and hundreds of functions.  When creating screen shots to include in your tutorials, remember these few items:

  • Show only the part of the screen you are referring to
  • Consider using small images of icons in your text when referencing icons in your instructions
  • Arrows and circles can aid in showing your reader exactly what you are referring to

Consider the following three examples:

Example 1

To change the font size, click the font size dropdown menu under the Character tab.


Example 2

To change the font size, click the font size dropdown menu under the Character tab.

Example 3

To change the font size, click the font size dropdown menu under the Character tab.

As you probably noticed these images get progressively more useful.  Example 1 shows the entire screen.  With this image, the reader would surely have a tough time finding the correct location on the screen.  This is especially true with software programs containing many tools and buttons.  A better approach is to zoom in to the location you want the reader to click as in Example 2.  The best approach is to also highlight in some way, with an arrow or circle, exactly where you want the reader to click.

Lifehacker.com has a great article featuring a list of five great screen capture tools for creating images for tutorials:

http://lifehacker.com/5218155/five-best-screen-capture-tools

Using Examples

Many forms of putting examples in your tutorials have already been discussed.  You should provide images and screenshots to further clarify steps to be taken.  You should include an example of what the final product will look like at the beginning of your tutorial.

Stories and real-life experiences can be handy to use in your tutorials.  Coming up with a personal experience or other example that has actually happened to yourself or someone else can help to illustrate a point and make the information you are presenting more meaningful.  When people read about real life and can relate to experiences, their retention of information will increase significantly.

Another way to use examples is to have the reader apply the information being taught.  In software tutorials many times this will inherently happen as you guide the user stepbystep through where to click and what to do.  This can also be accomplished by using some form of a quiz or activity that the user can take part in to demonstrate a principle just learned in the tutorial.

Writing Great Step-by-Step Instructions

            The bread and butter of your tutorial will most likely be in your step-by-step instructions.  This is where the rubber meets the road and the reader actually learns what they need to know.  It is important to make this part of your tutorials particularly clear, simple and consistent.

Throughout your tutorial, but especially in your step-by-step instructions, you should include clean, consistent and easy-to-read formatting.  Highlighting important aspects of the step you are walking the reader through is important.  If you are having them click a button, you could use a bold font for the name of the button.  Whatever you choose to do, make sure and use the same format throughout your tutorial.  This will help your reader know what to look for when following the steps.

Another important thing to remember is to be consistent with the way you phrase things.  For example: “Click OK” vs. “Push OK” vs. “Press OK.”

Consider the following two examples:

Example 1

Step 1 – To maximize the window click maximize at the bottom of the window

Step 2

Now press the button at the top that says open

Example 2

Step 1: To maximize the window click the Maximize button at the bottom of the main window

Step 2: Now that your window is maximized click the Openbutton at the top of the screen

As you can see from Example 1, the steps are not consistent:

  • Step 1 and Step 2 are formatted differently. Step 1 is bold with a dash and Step 2 includes the number sign and instructions on the next line.
  • Button labels are not designated consistently.
  • Different terminology is used to indicate button clicks: “click” vs. “press.”

The opposite is true for Example 2:

  • The step designations are both highlighted in green.
  • The second lines of the steps are indented as to further separate the instructions from the step designations.
  • Button labels are both highlighted in blue.
  • The same terminology is used to indicate clicking on a button.
For another great resource on step-by-step instructions visit http://eduscapes.com/tap/technical.pdf

Creating a Good “Frequently Asked Questions” Section

Have you ever called a government office or even a business or other organization and heard an automated message telling you common information like business hours, procedures, or directing you to other places?  If you’re not looking for this information, it seems a bit annoying to have to listen to it before you talk to an actual person.  But if you are wondering about business hours and are provided with that information quickly and effectively, then it is very efficient.

The Frequently Asked Questions section of your tutorial should serve the same purpose, only without the headache of having to listen to all the information on the phone before finally hearing the piece of information you were looking for.  Frequently Asked Question sections are to answer questions that would be common to your readers.

This supplement to your tutorial can serve to eliminate confusion and continually answer questions you are asked or that may be asked about your content.  It is important to continually update your Frequently Asked Questions[r1]  section with new questions that you may be asked all of the time.  If you are getting a question over and over again perhaps it would be better to change the content of your actual tutorial, in some instances, to eliminate the question altogether.  A common format for a FAQs sections is to print the question in bold and provide an answer below the question.

For more detailed information on how to write good frequently asked questions visit

http://www.freelancecopywritersblog.com/2130/who-to-write-a-great-faq-page/

Updating and Providing Support

Your tutorial should be treated as a living, breathing document.  After all, your tutorial most likely is on the Internet, and we all know things are constantly changing there.  Depending on the subject of your tutorial, your content may change quite a bit or it may not.  But regardless you should stay involved with your readers and make updates when necessary.

One way to do this is with message board functionality.  Equip your tutorial with a short message board or even a way for your readers to email you directly.  Whichever communication method you rely on make sure and stay engaged with your readers.  Respond to as many of their comments as time allows, especially those questions and comments geared directly toward you.  By doing this you will gain respect from your readers and set yourself up as an expert on the subject.  Readers will be more likely to return to your tutorial and other tutorials you write in the future.

An Interview with Kyle Charlesworth, Technical Writer at Grouplink

I have been privileged to know Kyle Charlesworth for many years.  He is an experienced writer and one whom I respect as someone who knows his craft.  The timing of the interview I had with Charlesworth was interesting.  I had largely already compiled the 10 tips that were covered in this chapter.  The chapter was essentially complete with all the needed information.  I was surprised how much the information in this article matched the same advice this seasoned technical writer gave me.

Throughout the interview with Charlesworth, familiar phrases and principles were heard.  Things like, “Defining your audience is crucial when deciding how to write a tutorial.” and “It is important to be clear, consistent, and concise when writing tutorials…you want your reader to learn something.”  But in all the similarities there was something different that I learned, something that transcends knowing all the rules and techniques.  It was the experience of someone who had actually put the tips and techniques to work – someone who knew all of the ins and outs and what really happens once you are out of the training and in the real world applying what you have learned.

The most important and valuable piece of information Charlesworth had to offer came on an unexpected subject.  That subject was the role that the writer has to actually communicate and connect with the reader.  In Charlesworth’s opinion the greatest tip was not how to properly format a sentence, how to properly display an image, or how to use an example in a tutorial.  It was a simple lesson of indirectly, through making it seem that you were at the reader’s side, connecting with them.

In speaking specifically about writing tutorials for software Charlesworth stated, “It isn’t just about being able to write well…you need to be able to know the software yourself, work with developers who generally are not easy to understand and translate that jargon into something very easy to understand for the reader.”  This is a skill that most people don’t really think about when they think about writing, especially technical writing.  Many times the subject is difficult to understand.  It is the tutorial writer’s responsibility to simplify that information and make it easy to understand.  Truly, something easier said than done.

This is not unlike what was talked about before.  The Internet is a complicated place, overflowing with a plethora of information.  However, if through this chaos of information overload you can master the art of providing clear, concise information you can be successful.  Through using these tools in obtaining the ultimate goal, that of connecting with your reader, your tutorials can be successful and you can make a difference to those you connect with and teach.

Other Great Resources

Other resources for finding even more tips like the ones above are:

Leave a comment

Filed under Uncategorized