Hiring a Technical Writer

Hiring a technical writer can be tricky, even if you happen to be one. Where can you find a technical writer? What characteristics should you look for? How can you tell a good writer from a bad one?

There are a number of career sites where you can hire technical writers. One in particular, Elance Find Technical Writers permits writers to bid on freelance jobs that employers post there. In my opinion, however, it is easier to hire a technical writer through your local chapter of the Society for Technical Communication (STC). Most, if not all, of the STC chapters have job banks where you can post employment opportunities. STC members in your area can then decide if they have the required qualifications to apply for the job.

Employers in India might prefer to use the job bank at Technical Writers of India.

You might be tempted to hire someone with expertise in your own field or industry. In fact, do not make knowledge of your industry a primary qualification when hiring a technical writer. Regardless of how much the candidates know about your industry, they will still have to learn about your product when you hire them.

What, then, should you look for when hiring a technical writer? You should look for someone who can:

  1. design a document that looks good both on paper and on line
  2. design a document that can be updated easily
  3. write instructions that are easy to understand

Now, before I continue, I should point out that there are many experienced technical writers who vehemently disagree with me. They believe that hiring writers with experience in a particular industry is more important than hiring people who can write well. If you are an experienced technical writer yourself, then certainly make industry knowledge a primary qualification for your candidates. You will be able to use your own writing skills to improve those of the person you hire. However, if you are not an experienced writer, your best bet is to follow the advice on this page and hire someone who already writes well. This person will be able to learn about your industry without creating problems for those who later have to update the documentation.

Document Design
A well-designed document is easy to look at, easy to read, and easy to update. Technical writers who create poorly designed documents create extra work for you down the line. Poorly designed documents are not only unpleasant for your customers to read, but they are also hard to maintain and hard to manage.

Before hiring a technical writer, consider the life cycle of the documentation that is to be written. If the documentation will provide instructions on how to use a particular product, then it will have to be updated as the product evolves. Updating documentation is similar to updating code. Just as software developers must be able to find the correct version of the source code, so must the writers be able to find the correct source files. But since the world does not abound with document management software (and, unless you have thousands of documents, you don't need it), try to hire someone who knows how to create an easy-to-understand file structure and a sensible file-naming scheme for the documentation. You can find out during the interview by asking candidates to describe how they will organize their source files.

To illustrate what can happen when documentation management is not taken into consideration, I was once hired by a company to redo the documentation for their flagship product. Nobody in the company knew where in the network I would find the existing documentation. After a morning-long search, I finally found the original user guide. In fact, I found two—both written in completely different styles by two different authors and stored in two different places in the network!

Just as important as being able to find the documentation easily is the ability to maintain and update it easily. Since documentation maintenance is regarded as a job for newbies, the task is usually assigned to someone other than the original author. This person is often a fledgling technical writer, but it could be an engineer or software developer. You will want this person to be able to open the source file and add, modify, or delete information without having to figure out how the document is structured. Indeed, it is the structure of the document that, more than the writing, determines how easy it is to update. A writer can find and fix a poorly written paragraph in a few minutes, but a poorly structured document can take weeks or months to repair.

To illustrate, let's say that my boss asks me to write, well, a limerick,

A typical limerick has a structure more or less like the following:
There once was a pummelled prizefighter,
Who longed for a life much politer;
At his last winning bout,
He bowed his way out,
And became a technical writer.
and later asks you to edit it. You change a word here, add a word there, and are finished with it in a couple of minutes. You don't even have to be good at writing limericks. But let's say that my "limerick" doesn't look or sound anything like a limerick. In fact, let's say that my limerick doesn't even rhyme. The only way to turn it into a limerick is to re-write it. Of course, you could just tell me to fix it, but what if I've moved on to a different project? Or a different company? You will have to fix the problem yourself, and you will need much more than a few minutes to do so.

So, how can you tell if a candidate knows how to structure a document? First, when you post the job description, ask that candidates send you their CV in Microsoft Word. Unlike a PDF document or an ASCII document, a Word document will give you a lot of information about the candidate's ability to design documentation.

Start by looking at the candidate's CV either on paper or on line with all of Word's layout features turned off. To turn the layout features off, proceed as follows:

  1. If paragraph markers show on the page, hide them by clicking the Show/Hide button in the toolbar.
  2. If table gridlines show, hide them by choosing Hide Gridlines from the Table menu.

A well-structured CV appears balanced on the page. Look for clear margins and a consistent use of white space around paragraphs and above headings. The page should not appear too dense with text. The left-hand alignment of the different page elements (headings, paragraphs, lists) should be consistent for each element:

  • Headings should be aligned with headings.
  • Paragraphs should be aligned with paragraphs.
  • Bullets should be aligned with bullets.
  • The space between a bullet and its text should be consistent throughout.

The CV should have no more than two fonts, neither of which should be Jokerman, Old English, or any other font that looks as though it belongs in a greeting card.

Now switch all the layout features back on:

  1. Click the Show/Hide button.
  2. From the Table menu, choose Show Gridlines.
  3. From the Tools menu, choose Options, then select the View tab.
  4. Under Formatting Marks, select the All checkbox and click OK.

If the CV has been formatted using tables, the table columns should be perfectly aligned. If the CV has been formatted using tab stops, then only one tab marker should appear between the text elements. The presence of multiple tab markers between text elements, however, should not be a primary reason for rejecting the CV. On the other hand, the presence of misaligned table columns is a serious flaw.

Determine how the author created white space above paragraphs and headings. If the author used paragraph returns to create white space (not the best method), the paragraph markers should all be the same size and the same distance apart. If you see white space but no paragraph markers or tables, the author is a superior document designer.

Check to see how the author created page breaks. A line across the bottom of the page with the words "Page Break" or "Section Break" or something similar is acceptable. A page break that occurs through no visible means is even better. However, if the author used paragraph returns to create page breaks, do not hire this person.

Do not be concerned about oddly placed page breaks, since these might occur if you are using a different printer from the author.

Check the spacing between words. Spacing is indicated with dots between each word. There should be only one dot between each word, except before the postal code in a Canadian address, which should be preceded by two spaces. If the author used multiple dots to create horizontal white space, do not hire this person.

Unless you are a superior speller and grammarian, do not pay much attention to the occasional red or green squiggly lines that may be visible in the CV.

Take a Bird's-Eye View of the Sample Document

Ask candidates to bring a paper version and an electronic version of a sample of their work to the interview. Do not reject any samples that are not "technical enough." The skills used to create a document called, say, "Creating Perfect Pastries" are the same as those used to create one called "Configuring the Network."

If the paper version of the sample document is stapled in the upper left-hand corner, remove the staple: you want to be able to turn the pages as though you are looking at a book. Examine the cover page. It should be uncluttered and the title should not be cute, whimsical, or clever. Rather, it should indicate what you will find in the book.

Note: Before trying out the following instructions in a live interview, it might be a good idea to practise them first using an ordinary book. Be aware, though, that there will be a few differences between the design of a book and the design of a technical document.

Frontmatter
Turn the cover page—just as you would open the cover of a book—so that the inside of the cover page is on the left and the next page is on the right. The inside front cover should be blank. The page on the right should be the title page, which restates the title. The title page might also contain a document number and version number if applicable, and perhaps some copyright information. Although the title page is page i of the document, there should be no page number on this page. If the page on the right is not the title page, but instead the table of contents (TOC), consider this a flaw in the design of the document, but not a serious flaw—it's just too common an error to be considered serious.

Turn the page as though turning the page of a book. The page on the left can be one of the following:

  • a blank page
  • a copyright page
  • a publication history page

Although this is page ii, the page number, as with the title page, should not appear on this page. If the left-hand page is the TOC, consider this a serious design flaw.

Unless the copyright information or the publication history extends to the right-hand page, the page on the right should (finally!) be the TOC. The page number (usually iii, depending on the position of the TOC in relation to the title page) should indeed appear on this page, and on every page thereafter, either in the header or footer.

Turn the page. The left-hand page should either be a continuation of the TOC, or else it should be blank except for the header and footer. The words "This page intentionally left blank" should never be seen on any blank page.

The right-hand page should be the introduction to the document. It might also be entitled "About This Document" or something similar. The page number should still be a Roman numeral. If the introduction precedes the TOC, do not consider this a design flaw.

Turn the page. The left-hand page should either be a continuation of the introduction, or else it should be blank except for the header and footer.

Chapters
The right-hand page should be the first chapter, although the title does not have to specify this. That is, if "Chapter 1" does not appear in the title, it is not a design flaw. The first page of the first chapter is page 1. Page numbering should continue in Arabic numerals on every page thereafter. Some authors precede the page number with the chapter number (1-1, 1-2, etc.). In this case, each new chapter begins on page 1 (2-1, 3-1, etc.). While it is my opinion that this method of numbering pages impedes the usability of the document, many authors regard it as good practice; you should not, therefore, consider it a design flaw.

Flip through the document until you get to the last page of the last chapter. If the last chapter ends on a right-hand page, the next left-hand page should be blank except for the header and footer.

Backmatter
The next right-hand page should be the glossary. The final version of every technical document should include a glossary, which contains full definitions—not just a list of acronyms and their expansions—of the acronyms and technical terms used in the document.

If the document contains an appendix, it should come after the glossary, beginning on a right-hand page.

After the glossary (or the appendix, if applicable), you should find the index, beginning on a right-hand page. However, because indexes take so much time to create, they are often regarded as "nice to have" rather than essential. Not all technical documents, therefore, contain an index.

After the index (or glossary or appendix, as applicable), the next right-hand page should be the inside back cover, which should be completely blank. The flipside of the inside back cover is of course the back cover, which can either be blank, or else it can contain information about the book (title, document number, etc.) in a small type size.

Take a Closer Look at the Sample Document

Now go back to the TOC and, for about 20% of the entries, verify that the headings are worded exactly the same as the headings they refer to, and that they appear on the page specified. In other words, if the TOC says that you will find a heading called "The Business Environment" on page 5, go to page 5 and check. Since all desktop publishers generate TOCs electronically, any differences between the entry in the TOC and the page to which it refers indicate that the candidate hard-coded TOC. This as a serious design flaw, and indicates that there will be other serious problems with the document. Unless you will be able to teach the candidate how to use the desktop publishing software, do not hire this person.

Flip through the document and scan the page numbers. Are they sequential? Check the page number on the right-hand pages. It should always be an odd number. Any problems with page numbering should be regarded as serious design flaws. Some documents, however, do not have a page number on the first page of a chapter. This should not be considered a design flaw.

Turn to any chapter that has three or more pages. The first page of the chapter should have a different appearance—"look and feel"—from the two pages that follow it. The difference might be slight or it might be quite striking. Since there are many ways to accomplish this difference, you should not regard the design as flawed unless there is no difference.

In any chapter that has three or more pages, examine the headers and footers of the two pages immediately after the first page of the chapter. There are only three acceptable positions for any element in the header and footer—left, center, or right. The position of the elements in the header and footer on one page should mirror the position of the elements in the header and footer on the facing page. (This rule does not apply to the first page of a chapter.) Thus, if the left-hand page has the page number in the left-hand corner, then the right-hand page should have the page number in the right-hand corner.

Note that it is the relative position of these elements, as well as their weight, that should be the same; the content might be different. For example, while the position of the page number on one page mirrors the position of the page number on the facing page, each number is of course different. Likewise, if there is bolded text at the right-hand side of one header, there should be bolded text at the left-hand side of the other header. Finally, aside from the page number, which must appear somewhere on these pages, headers and footers do not have to contain any information at all!

Now read part of the document. It should be easy to read and easy to understand, even if you know nothing about the subject. You should be able to understand it without having to concentrate too hard. You should not be confused by what you are reading; neither should you feel depressed by the thought of having to read another paragraph. Be aware, though, that problems with a product will create problems with the user guide. Thus, if you have trouble understanding something in the sample document, ask yourself, "Is the document badly written, or is the product badly designed?"

To illustrate: I once documented a GUI that had two Modify buttons!

If the sample document contains a step-action procedure, check that each step describes the required action as follows:

  • The first clause describes where the action occurs. This is called "situating the user."
  • The second clause describes what the action is.

Thus, "From the Table menu, choose Show Gridlines" is correct, but "Choose Show Gridlines in the Table menu" is not. Of course, it is not necessary to situate the user if there is no doubt about where the action is taking place.

Check the Electronic Version of the Sample Document

Open the sample document on your computer. Ensure that all the layout features are switched on, as they were when you looked at the candidate's CV:
  1. Click the Show/Hide button.
  2. From the Table menu, choose Show Gridlines.
  3. From the Tools menu, choose Options, then select the View tab.
  4. Under Formatting Marks, select the All checkbox and click OK.

Also, turn on field shading:

  1. From the Tools menu, choose Options, then select the View tab.
  2. In the Field Shading box, select Always and click OK.
When the field shading feature is turned on, Word displays any electronically-generated text and numbers within a gray box.

Go to the TOC. If you have set field shading to Always, the TOC should appear within a gray box. If there is no gray box, do not hire the author of the document unless you are willing to teach this person how to use the desktop-publishing software.

Go to any page within the document and find the page number. Since page numbers are electronically generated, they too should appear within a gray box.

Ask the candidate to show you a cross-reference in the sample document. The wording of the cross-reference will be something like "For more information about WIN, see page 25." The page number should appear within a gray box. If the cross-reference mentions a title (as in ". . . see Wireless Intelligent Networks on page 25"), the title should also appear within a gray box. If there are no gray boxes, do not hire the author of the document unless you are willing to train this person.

Find a table (or a graphic) within the document. If the table has a caption and the caption refers to the table number (as in "Table 13: Population Distribution in Major Canadian Cities"), the table number should be within a gray box. If it is not, do not hire the author of the document unless you are willing to train this person.

Check that the columns of the table are aligned throughout the entire table.

Ask the candidate to show you a place in the sample document that was formatted with tab stops. Only one tab marker should appear between the text elements. While multiple tab markers are not a serious problem in a CV, they are a major pain in a technical document. On the other hand, it is really easy to retrain the writer: "I see that you have used multiple tab stops between text elements. If I hire you, please ensure that you use only one."

Hiring an Inexperienced Technical Writer

Candidates who do not have much technical writing experience need not necessarily be relegated to the rejects pile. For example, candidates who got good grades on essays at university or who have had letters published in the newspaper clearly know how to organize their thoughts and write them down convincingly.

The main difficulty with hiring inexperienced writers is that they probably do not know how to use the desktop publishing software properly, which will lead to the design problems described above. However, if your company uses well-designed templates and if someone can supervise the writer closely for the first few months, there is no reason why you shouldn't hire a less experienced writer.

Inexperienced writers might not have much to show you—perhaps just a letter or an article. In this situation, you should read their samples quite closely so that you can determine how convincingly they have formulated their arguments.

Find interviews intimidating?
If you are a new manager interviewing people for the first time or if you are interviewing candidates for a position that requires skills outside your own field of knowledge, you might regard the interview process as a nerve-wracking experience. 7 Interviewer Interview Questions for First-Timers provides some great tips so that you can interview candidates with confidence.

Google
Webwww.docsymmetry.com