Monday, February 22, 2010

How to Prepare for a Technical Writing Test

writing testRelatively speaking, writing is an easy skill to test. So the number of employers who don't ask to see a portfolio when they are looking for technical writers is quite surprising.

However, a good portion of those employers who take seriously the task of filling a technical writing position do want to see examples of your writing. Because of this, you should always have a varied and up-to-date portfolio ready when you start looking for technical writing jobs. You should have each writing sample available in both hard copy and digital form.

For the hard copy versions, you should make them double sided, and in colour. Ideally, the digital copies should be in PDF.

And, as you look for a job as a technical writer, you should be prepared to do a writing test at some point.

I have encountered two types of writing tests during the technical writer job interview process: the basic test, and the advanced test.

The Basic Technical Writing Test

The basic writing test is usually administered on the premises of the organization with which you are interviewing. The test is given to check your writing ability, how well you conform to the conventions and structure associated with technical writing, and how quickly you can produce results.

The basic test will inevitably ask you to write a set of instructions for a simple task. Some of the most common tasks that show up on the writing test are:
  • Making a sandwich
  • Making a cup of coffee
  • Planting a tree
But wait, you might be asking, what do these tasks have to do with technical writing? The choice of a mundane, every day task is to ensure that everyone taking the test knows how to perform it and can write about it to some degree. Again, it's all about demonstrating structure and conventions.

So how should you write the set of instructions? First, ensure that the title that you give the instructions includes a gerund. In other words, if you are writing instructions about how to make a sandwich, entitle it Making a Sandwich, instead of How To Make a Sandwich. Why? Because it is standard in most technical writing to include a gerund in instruction titles.

This is despite the fact that the "how to" designation is a much more common term for people to type into search engines. But the goal here is to show that you are aware of technical writing conventions, not to make the instructions more searchable online.

Writing the Introduction

Second, include a clear purpose statement in the introduction. Something along the lines of "The following instructions will show you how to make a sandwich."

Then, mention who the intended audience is for the instructions. This might seem superfluous, but I would include it to let your potential employer know that you are familiar with intended-audience statements. This statement could be something like "These instructions are intended for those with a basic understanding of using kitchen utensils."

Next, indicate how many tasks are included in the instructions. To see more information on breaking instructions into tasks, see this post. When you state how many tasks there are, format them in a bulleted list. If there is only one task, you do not need to preview it in the introduction—doing so would be redundant.

Next, include a list of what is required to perform the instructions.

Finally, you may want to include a time estimate of how long the instructions should take to perform.

Writing the Steps

After you have written the introduction, begin the instructions with an infinitive clause. For example, To make a sandwich: If you are doing the writing test on a computer, you should bold the infinitive clause. Using bolding and other intra-text highlighting methods indicate further knowledge of good technical writing.

Then proceed with writing the actual instructions.Make sure to adhere to the rule of seven when writing the steps.

Within the instructions, it is probably a good idea to include at least one warning, caution, or note. If you have enough time, you may want to include one of each. I won't go into the details of how to format and write this kind of extra information, but you should make each type stand out in a unique way.

When you have completed the instructions, you may want to include a closing statement. Some kind of feel-good sentence like "If you have followed the above instructions, you now have a completed sandwich." However, be careful not to get too cutesy here. Some technical writers loathe fluff of any kind.

Be absolutely certain to maintain consistent terminology throughout your instructions. For example, if you refer to a slice of bread in the introduction, do not call it a piece of bread in one of the steps.

Because you know that you are likely to come across the basic writing test, prepare a few sets if instructions in advance and commit them to memory. Then, regurgitate the relevant one when you are called upon to create a set of instructions during a writing test, and you will impress with your efficiency and the quality of the final product.

Other Components in the Basic Writing Test

But wait, there could be more to the basic writing test than just a set of instructions! You will probably also be asked to highlight mistakes in a series of sentences, and/or re-write them. I won't go into the details about how to do well on this section—that's really down to whether you have the fundamentals of grammar mastered. However, look for the old chestnuts to show up here—its and it's, there, their and they're, and subject and verb agreement, to name a few.

You may also encounter a section that asks you to demonstrate your creative writing skills. After all, as a technical writer you will be asked to tailor your writing to specific audiences, industries, and types of documents. Writing a white paper or proposal is much different than writing a user manual. Common topics that you might be asked to write about are:
  • A recent holiday you took
  • A book you read
  • A movie you saw
I would generally keep this kind of mini-essay as simple as possible. Remember the basic five paragraph college essay? Start with an attention grabbing introduction, and include a thesis sentence and a preview of what is to come. Then, follow with three body paragraphs, and a conclusion. This demonstrates that you are always conscious of structure and also allows you to show-off your writing skills.

The Advanced Technical Writing Test

More advanced writing tests are not uncommon. These may crop up when the position requires more technical knowledge.

One possible version of the advanced test will see you presented with a jumble of specifications for a product or piece of software. The scenario that is being suggested is that an engineer has given you this information and you are expected to format it using language that will be appropriate for the intended audience. In this case, I would essentially adhere to the advice that I have given above regarding the basic test. In other words, format the information into a set of instructions (unless it specifies otherwise on the test). However, there are some important things to keep in mind with the advanced writing test.

First, the convoluted information that you receive will no doubt include a lot of false assumptions about the knowledge level of the end user. Therefore, you must take numerous sentences and paraphrase them in a way that will allow a novice to understand. Try to eliminate as much jargon as possible.

Clear and understandable prose is always the goal with technical writing. Change as many passive voice sentences as possible into active voice (again, don't overdo it here—some sentences are simply more appropriate when written in the passive voice), and make sure that there are not too many overly long sentences larded down with numerous clauses. Of course, you don't want to go overboard with short sentences either. Otherwise, your writing will sound too choppy. A good mix of sentence length is always best.

These are only a few of the writing test possibilities you may encounter during your search for a technical writing job. No doubt there are other variations that appear as well, both depending on the industry and the specific organization to which you are applying. I could easily imagine a test that asks you to quickly learn about a software program with which you are unfamiliar and then write out instructions for a basic task using that software.

When approaching any writing test, you should aim to be as prepared as possible and know what skills you want to demonstrate to potential employers.

Monday, February 15, 2010

Technical Writing: Instructions and the Rule of Seven

When writing a set of instructions, you should try to use no more than seven steps. The reason for this is simple: cognitive fluency. In other words, when people look at a set of instructions and see any more than seven steps, their first impression is: this is going to be difficult.

This may be a reaction that only registers subconsciously, but the result is that the user's attitude towards both the instructions and the product takes a negative turn

You must be saying to yourself, "but what if there really is 10, 14, or even 30 steps?!"

Break Instructions into Different Tasks

Adhering to this rule does not mean that you eliminate steps from your instructions. It simply means that you break down the instructions into separate tasks so that they are easier for the user to digest. The result is that the instructions you write become much more effective.

Here is an example of a set of instructions with 14 steps, followed by revised instructions with two tasks, both of which do not exceed the magic number seven. The topic is not relevant—in fact, I have chosen something that most people are already familiar with.

To make spaghetti:

1. Fill a pot with water.

2. Put the pot on on element on a stove.

3. Turn the element to the highest setting.

4. When the water is boiling, place one serving of dry spaghetti into the pot.

5. Cook the spaghetti for 7–8 minutes.

6. Place a colander in the kitchen sink.

7. Turn off the element.

8. Lift the pot off the element and pour the spaghetti into the colander.

9. Pour spaghetti sauce into the pot.

10. Pour the spaghetti from the colander into the pot containing the sauce.

11. Put the pot back on the stove.

12. Turn the element on to medium.

13. Stir the spaghetti and the sauce for 3 minutes.

14. Use a spoon to place the spaghetti onto a plate.

Revised Instructions

Here are the instructions revised so that they adhere to the rule of seven.

To cook the spaghetti:

1. Fill a pot with water.

2. Put the pot on on element on a stove.

3. Turn the element to the highest setting.

4. When the water is boiling, place one serving of dry spaghetti into the pot.

5. Cook the spaghetti for 7–8 minutes.

6. Place a colander in the kitchen sink.

7. Turn off the element.

To plate the spaghetti:

1. Lift the pot off the element and pour the spaghetti into the colander.

2. Pour spaghetti sauce into the pot.

3. Pour the spaghetti from the colander into the pot containing the sauce.

4. Put the pot back on the stove.

5. Turn the element on to medium.

6. Stir the spaghetti and the sauce for 3 minutes.

7. Use a spoon to place the spaghetti onto a plate.

Does this mean that you absolutely never go beyond seven steps? No, of course not. This is only a guideline (and "the rule of seven" sounds good). Often I will include as many as 10 steps when there is no logical way to break down the instructions into two tasks. When breaking a set of instructions into multiple tasks, one challenge that arises is coming up with a good infinitive clause to introduce the instructions ("To plate the spaghetti" is quite weak).

Do not compromise the quality of your written instructions simply to follow this rule. Remember, writing is not science. But this is definitely a helpful standard to keep in mind.

Saturday, February 13, 2010

How to Add Radio Buttons to MS Word 2007 Documents

Radio buttons, or option buttons as Microsoft now refers to them, are used in online questionnaires, and forms that require users to make a selection.

This tutorial demonstrates how to insert radio buttons into a document in Microsoft Word 2007, using a PC with Windows XP or Vista. The tutorial consists of two tasks:

  • Adding the Developer tab to the ribbon
  • Inserting option buttons into an MS Word document
For the remainder of this tutorial, the term "option button" will be used instead of "radio button."

To add the Developer tab to the ribbon:

1. Open Microsoft Word 2007.

2. In the upper left corner, click the Microsoft Office Button.

Microsoft Office Button

3. Click the Word Options button.

word options button

4. In the Word Options dialog box that appears, select Popular.

Popular in word options dialog box

Note: Popular is the default selection.

5. Click the check box next to Show Developer tab in the Ribbon.

show developer tab in the ribbon

Note: you want the check box enabled, i.e., with a check mark.

6. Click OK.

OK button

The Developer tab now appears in the Microsoft Windows 2007 ribbon.

To insert option buttons into an MS Word document:

1. Click the Developer tab.

Developer tab

2. In the Controls group, click the Design Mode button.

Design Mode button

Note: you want the Design Mode button enabled. When it is enabled, it is highlighted in orange.

3. In the Controls group, click the Legacy Tools button.

Legacy Tools button

Tip: When you click the Legacy Tools button, if you have not already clicked the Design Mode button, the Design Mode button will now be enabled.

4. Under Active X Controls, click Option Button.

Active X Controls option button

Result: An option button now appears in the MS Word document.

5. Hover your cursor inside the option button, right click, and point to OptionButton Object, and click Edit.

Edit option button

Result: the colour of the option button changes, which indicates that you can now edit the text.

edit option button change colour

6. Use the left arrow backspace key on your keyboard to delete the default text, and change the text to suit your preference.

edit option text box

Tip: if the text you want to add exceeds the default size of the option button text box, click on the black square on the right side of the box so that a double sided arrow appears, and drag to the right.

drag option button text box double sided arrow

7. Click outside the option button.

8. Click the Design Mode button so that it is disabled.

The radio button is now active—i.e., you can click it and a dark circle will appear inside, indicating that it is the option that you have selected. Add as many more option boxes as you like, and preface the series of options with a question, statement, or instructions.

Wednesday, February 10, 2010

The Death of the Radio Button

In the most recent Microsoft Style Guide for Technical Publications, radio buttons are now referred to as option buttons. First, let me clarify exactly what I am referring to. The following circles that appear next to the three answer options after the question are radio buttons:

radio buttons

Everyone has seen radio buttons in online forms. You can only select one option (usually). When you select another option, the previous option that you selected becomes blank, or "pops out."

The name radio button was originally used to describe this type of online form element because the select-one-option-and-the-previously-selected-option-is-deselected behaviour replicated the action of buttons on old car radios.

old car radioHowever, even for people who do remember the enjoyable and oddly pleasing sensation of changing the station by stabbing one of those chunky buttons, the radio button moniker for those circles next to answer options in online forms usually left people shaking their heads.

The problem was further compounded by the large number of people who are too young to remember those old radios.

Also, think of the many parts of the world where cars were few and far between only a few years ago, especially in rural areas. Many people in those countries never would have had a chance to see an old car radio, regardless of their age. Those same places are now experiencing huge technological growth, and will soon have, in real numbers, more computer users than anywhere else.

The funny thing is, many people still have never heard the term radio button to describe internet answer options. The term does not always accompany usage of the radio button/option button in online forms. It is often only used in help files, or other documentation.

In short, the term radio button confused a hell of a lot of people!

Microsoft recognized this confusion, and has now started using the term option buttons.

Now, the question is, do you select, click, choose, or enable an option button? The answer depends! You have probably seen all four words used when reading instructions for filling in an online form. The most important point to remember is, use one word consistently in a document.