How to Prepare for a Technical Writing Test

Relatively 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 purpose 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 indicates 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.

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 contents 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 contents 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.

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.






3. Click the Word Options button.







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

Note: Popular is the default selection.

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

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

6. Click OK.






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.





2. In the Controls group, click the 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.

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.

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.

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

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

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.

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.

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:












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.

However, 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 is...it 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.

Using Hyphens, En-dashes, and Em-dashes

Many writers and a whole lot of readers do not know the difference between hyphens, en-dashes, and em-dashes. This article explains when to use each one, and how to add each one using your keyboard.

Hyphens

The hyphen is used for joining words in various types of compound constructions. There are numerous examples including compound nouns, adjectives, and verbs. I will not delve into the specific rules of using hyphens in these situations. More importantly, once you have read the rules regarding en-dashes and em-dashes, you will at least know when not to use hyphens.

Similarly, hyphens are used to join some prefixes and suffixes to nouns, adjectives, or verbs.

Hyphens are also used for joining parts of a word that have been separated by a line break.

You can also use hyphens to indicate the spelling of a word. For example, "Any decent Scrabble player knows the letter h is spelled a-i-t-c-h."

When you want to emphasize clear enunciation, use the hyphen as well: "I said, 'be qui-et!'"

The hyphen key appears on the top row on your keyboard, to the right of the zero. It also appears in the upper right hand corner of the number pad.

En-dashes

Notice than the en-dash is slightly bigger than the hyphen. The en-dash is so named because it is supposedly the length of a letter n.

En-dashes are used to separate compound expressions. Many compound expressions are geographical areas. For example, the San Francisco–Bay Area.

You also use en-dashes to indicate a range of numbers. For example, when writing the years a person lived: Jim Morrison (1943–1971). Or, for a range of pages: "Read pages 5–12."

The easiest way to insert an en-dash is using the shortcut:

—Hold down the Alt key on your keyboard
—Type the numbers 0–1–5–0 on your keyboard's number pad (Num Lock key must be activated)
—Release the Alt key

The en-dash appears.

In Microsoft Word, you can also add an en-dash in this way: add a space after the word you want the en-dash to follow, press the hyphen key twice, and then continue typing. Microsoft Word will then convert the two hyphens to an en-dash. However, it is good practice to go back and delete the initial space that you added. Most style guides suggest that you put no space before or after an en-dash.

Em-dashes

The em-dash is the longest of the three. The em-dash is so named because it is supposedly the length of the letter m.

Em-dashes are used mainly to set off explanations within sentences. Many writers will often use round brackets (parentheses) in these situations. Often, the two are interchangeable though some will argue that there are differences and nuances.

For example: He met with other cruciverbalists—lovers of crossword puzzles—every Sunday night.

Em-dashes can also be used in place of colons in titles. And they can be used in place of bullets in vertical lists.

To add an em-dash, press Alt + 0151 on your keyboard.

Or, in Microsoft Word, immediately after the word that you want the em-dash to follow, press the hyphen key twice, and then continue typing. Microsoft Word converts two hyphens to an em-dash. As with en-dashes, most style guides suggest that you put no space before or after an em-dash.

Summary

Hyphen -
En-dash –
Em-dash —

And those are the basics for using hyphens, en-dashes, and em-dashes. Knowing how to use these correctly will set you apart from many writers.

Disputed Grammar: Subject and Verb Agreement

It's easy to get into a disagreement over grammar. There is a whole field of study dedicated to disputed grammar. So why does English grammar cause so many arguments? Because there is no final say when it comes to English grammar, the language is constantly changing, and there are many people who simply disagree on various points. The fact that there are now so many unreliable and incomplete sources online only adds to the confusion.

I recently found this website and at first liked the list dedicated to subject and verb agreement. However, when I came to rule number 13, I found it a bit lacking. Here's what rule 13 says:

Rule 13. Sometimes the pronoun who, that, or which is the subject of a verb in the middle of the sentence. The pronouns who, that, and which become singular or plural according to the noun directly in front of them. So, if that noun is singular, use a singular verb. If it is plural, use a plural verb.

Examples: Salma is the scientist who writes/write the reports.
The word in front of who is scientist, which is singular. Therefore, use the singular verb writes.
He is one of the men who does/do the work.
The word in front of who is men, which is plural. Therefore, use the plural verb do.

I agree with the rule to a point. However, it implies that in any situation in which a dependent clause starts with who, which, or that, the relative pronoun will always refer to the noun that comes directly before it. That simply isn't true.

My First E-mail

I sent an e-mail to the owner of the website, Jane Straus. Here's what I said in my e-mail:

Hello Jane,

I found your list of subject and verb agreement rules on your website very concise and helpful. Number 13 especially is one that is usually not included in such lists. However, I believe that the explanation in rule number 13 needs clarification.

I've never read such a strict interpretation of the rule. I've always seen it only in reference to the phrases "one of those people who" or "one of those things that" (or slight variations), which also happens to be the example you use. If that rule were to apply universally, then this sentence, which I found on the front page of a corporate website, would be correct:

"This is a collection of automated tools that enable developers to protect their application code against tampering, reverse engineering and automated attacks."

In fact, I believe that the above sentence is incorrect and "enable" should have an "s." Yet it has a dependent clause starting with "that." If we were to follow rule 13 in this case, then the sentence would be considered correct.

I find that the first sentence in rule 13 is quite vague and could lead to more confusion.

I would love to get some feedback from you on this.

Thanks.

Her Response

While Jane did not respond to me directly, her assistant did. Here's what she had to say:

Dear Ken,

Jane is unable to answer your query at this time. I have to say that I agree with her regarding its application to your example. I would use "enable," as well. The tools are the objects that enable the users, not the collection. I hope this helps you.

Best wishes,

My Response

I found her response completely unconvincing. So I quickly sent back a reply:

Hello,

Thanks for your response. However, I'm still not convinced.

When a prepositional phrase comes between the subject of a sentence and the verb, the subject still determines whether the verb is singular or plural. The only exception that I've seen is the example Jane used. But I've never seen it applied so broadly as her rule implies and as you're suggesting.

You wouldn't say, "This is a collection that enable developers...."

Nor would you say, "The pile of clothes stink." (Though many people incorrectly do.)

I know the above example is not followed by a dependent clause, but I am trying to demonstrate the basic premise on which I am basing my belief.

The exception that Jane points out has been articulated elsewhere as:

"The phrases 'one of those who' and 'one of the things that' take plural verbs, as in 'The comma splice is one of those errors that always slip past me,' and 'One of the things that drive me nuts is subject-verb agreement.'"

It sounds right, and the explanation makes sense. Yet on Jane's website that rule is explained in a way that applies to so many other examples.

And the explanation that you provided just doesn't wash: "The tools are the objects that enable the users, not the collection."

If that were a valid explanation, then the noun in a prepositional phrase (which is the object of the preposition and not the subject of the sentence) would determine whether a verb is singular or plural in every case.

If there is a valid explanation for applying that rule so broadly, I would love to hear it.

I challenge you to find that rule anywhere else defined so broadly. I've only ever found it explained using the "one of those who" or "one of those things that" phrases (or with slight variations but the same basic construction).

Anyway, I hope you take these messages in the way that they are intended. I love language and grammar and all the related discussions.

Sincerely,
Ken

Jane's Assistant Responds

I found the second response from Jane's assistant similarly inadequate:

Dear Ken,

I think you have your own answer embedded in your query: "The above example is not followed by a dependent clause." You are absolutely correct that in the typical case, the subject of a prepositional phrase, not the object, determines the verb's expression. The key distinction in your original example is the dependent clause.

I hope this helps.

Best wishes,

To Summarize

But she missed the point completely. Rule number 13 on Jane Straus's website is inadequate, and in fact, could lead to incorrect subject and verb agreement usage.

Now that I read the list more closely, I realize that there is no explicit rule to deal with prepositional phrases (except rule 9, which is another exception to the prepositional phrase rule).

Most people who have a decent grasp of grammar know the problems that prepositional phrases can cause for subject and verb agreement. I covered this point in one of my e-mails to Jane's assistant. To reiterate, when a prepositional phrase comes between the subject of a sentence and the verb, the noun in the prepositional phrase does not determine whether the verb is singular or plural. However, as with most "rules" in grammar, there are a few exceptions. Here is my best reading of the exception that I have been discussing here:

When the phrase "one of those people who" or "one of those things that" (or slight variations that follow the same construction) is followed by a dependent clause starting with who, that, or which, the relative pronoun can possibly refer to the noun that immediately precedes it (which is the noun in the prepositional phrase). In that case, the main verb in the sentence will agree with the noun that is part of the prepositional phrase.

(Note: the prepositional phrase within the phrase is "of those people" or "of those things.")

But that is not always the case.

For example, look at these two sentences:

1. He is one of the goalies who actually stops the puck on a regular basis.
2. He is one of the goalies who play on the team.

In the first sentence, the verb "stops" is clearly referring to "one". In the second, "play" clearly refers to the goalies.

So, the most important question to ask in a situation where one of the relevant phrases and the dependent clause with who, that, or which are present is: To which noun is the relative pronoun referring?

Do not adhere to some supposed rule that states that the relative pronoun in such cases always refers to the noun immediately preceding it, because it's not true. In fact, always (heh!) be wary of grammar rules that use the word "always," or "never." There is usually an exception to the rule.

And I'm fairly certain, as I stated earlier, that the sentence I found on the corporate website:

"This is a collection of automated tools that enable developers to protect their application code against tampering, reverse engineering and automated attacks."

is wrong, and "enable" should have an "s."

(Note:in the above sentence, the prepositional phrase is "of automated tools.")

Weigh In

However, I'm still open to interpretations that prove that I am wrong on this. I am constantly learning about grammar and the English language, and updating concepts that I thought I had down cold. When trying to untangle a grammar conundrum, I always ask myself two questions regarding a supposed rule:

Does the usage in the rule's relevant examples sound right?
Does the explanation that backs up the rule make sense?

So, let me know what you think. Who is right about this? Leave a comment or respond to the poll that I have added to the sidebar.

Technical Writing and the Slender Yellow Fruit Syndrome

I first read about the slender yellow fruit syndrome in the book Woe is I by Patricia T. O’Conner. The term refers to the over-the-top attempts by some writers to vary the language they use to identify something more than once in a sentence or passage. In general, using a variety of language is a good idea—especially in creative writing. Reading the same word repeatedly can get tiresome. That’s one reason we have pronouns.

However, some writers take this concept too far. When you have to refer to a banana twice in the same sentence, do it! It's not the end of the world. Calling a banana a "slender yellow fruit" for the sake of variation is absurd.

This is even more important in the world of technical writing. Technical writing should follow a clear, predictable pattern, and there should be no problem solving involved for the reader. One way to maintain clarity is to establish terms of reference early on in a document (or even state them explicitly in the introduction) and then stick to them. Shifting terminology is a guaranteed way to confuse readers.

This does not only apply to nouns, but other parts of speech as well. If you tell the reader to "select" the radio button on page one, do not then tell them to "enable" the radio button on page two.

An easy way to avoid shifting terminology is to write out a style sheet for the document on which you are working. You can refer to the style sheet when you are writing. And later, when you perform an edit on the document, you can devote a complete pass to each major term. The style sheet can (and should) contain more than just the important terms that you are going to use in your document. It should also include formatting issues such when to apply bolding, and the font style and size for headings.

A style sheet for each project can complement a company style guide, which in turn can complement a commercial style manual, such as the Chicago Manual of Style. When you encounter a style or usage issue that is not in the style sheet, reference the company style guide. And, when you inevitably have a question concerning language that is not covered in the company style guide, check the manual.

If you are in a small organization, creating a style guide is a very wise time investment. The amount of effort that is spent writing the guide will be earned back in spades later on when time is saved during the editing process. And a document that adheres to a style guide will be more consistent and effective than one that does not.

So, vary your language in creative writing, but not to an absurd degree. And in technical writing, be very careful about ever straying from the terms of reference that you have established.