Maybe you don’t hear your accent, but others do. When you read their documents, does the accent come through?

We all judge people by how they speak. It’s easy.

When I was a kid, I had a strong regional accent. I grew up near the countryside and thought that was the way people spoke. Well, we all did.

When I went to college, a teacher told us to polish our accents if we wanted to get ahead. He was right.

Name one CEO or world figure with a strong regional accent? It gets ironed out along the way.

Today, I have hardly any accent.

Years of trying to smooth out the rough edges and blend in have diluted what was there. Most think I’m American, French (dunno!) or Russian (they go by the name, I guess).

Seth Godin asks if your writing has an accent?

“Of course it can. Not just grammar errors, but sentence length, exclamation marks and your vocabulary all tag you. And the fonts, colors, pictures and layouts you choose are part of your accent as well.”

So, here’s my question.

When you review other people’s documents, what can you tell about them? Does the way they ‘speak’ influence the decisions you make based on their material?

Flip it around.

When they read your documents, what do they think?

“Don’t worry” she said. “No one reads this stuff anyway. Just get it done.” Sounds familiar?

These were the words a former Project Manager once told me. I’d written 20,000 words for a banking system – and no-one would read it.

What do you do when your own company has such a poor view of tech docs?

Are you wasting your time?

Does anyone actually read them?

Sure, they must.

Well, how do you know?

Creating a training plan? Before you do this, you need to step a step back and work out what your colleagues need to learn.

Why?

Well, otherwise, you risk developing a training plan that overlooks the areas where people really need to skill up.

The advantage of a well-developed training is that it lets you focus your skills, as a trainer, and match the training course to the audience.

One way I do this is to develop a Target Audience Questionnaire.

Download: Free Target Audience Questionnaire

What is a Target Audience Questionnaire?

Audience Analysis is used to profile, i.e. learn about, your target audience, so that you can then offer better products, services, training, books or whatever… that match their specific requirements. This is different than gathering requirements, which is more a wish list, of what people want.

Audience Analysis is a snapshot of what your users/readers/viewers etc are doing here and now. Marketing plans also use these to get an better understanding of how to segment their audiences.

For technical writers and trainers, you can use this Target Audience Questionnaire when developing your next set of documents or training plan.

What’s important is that you see the value in this activity.

The more you know about your target audience, the more likely your material will suits their needs.

So, let’s get started.

What goes into a Target Audience Questionnaire?

You need to cover four sections in your questionnaire: document details, objective, experience, tasks.

1. Document Details

The first page of the questionnaire—usually near the header—captures information related to the actual document, for example, the name of the course, the individual, date, and department. Depending on your project, you may want to adjust this to suit your needs.

Some technical writers use version controls on their documents, as well as the document’s status, for example, Draft, Revised, Final or Approved.

Course:

Name:

Date:

Department:

2.Objectives

In the objective section, describe the goal of this questionnaire.

• Who are the project stakeholders for this project?
• Who is been asked to complete this questionnaire?
• What is your motive for doing this?
• What is the benefit to the reader?
• When does this questionnaire need to be completed by?
• Where will the information be kept, share, distributed, and archived?
• Why should the reader/user/employee complete this questionnaire? Is it compulsory? Is there a date by when this must be completed?
• How does this questionnaire fit into the company’s overall strategy?

Sample text:

“To help us provide the most appropriate the training to our employees—so you have the necessary skills, knowledge and confidence in your own abilities—please study the following questions and answer them to the best of your abilities.”

The questionnaire must be completed by [date].

The questionnaire is approved by the [project board].

Contact [identify the person] if you have any queries about this questionnaire.

3. Level of Experience

Identify your level of expertise with these tools based on a scale of 1 to 5.

(1=No Experience; 5=Extremely Experienced).

1.         Adobe Acrobat (not Acrobat Reader)

2.         Adobe FrameMaker

3.         AuthorIT

4.         DocBook

5.         DocToHelp

6.         DreamWeaver

7.         Epic Editor

8.         ForeHelp

9.         Interleaf

10.       MadCap Blaze

11.       Madcap Flare

12.       Microsoft Excel

13.       Microsoft Visio

14.       Microsoft Visio

15.       Microsoft Word

16.       RoboHelp

17.       Techsmith Camtasia

18.       Techsmith Snagit

19.       WebWorks

20.       XML editor

4. Tasks & Activities

Please indicate all answers that are applicable to your role.

1. How often are you asked to provide [technical documents/status reports/management reports etc]?

(a) Several times a day

(b) Several times a week

(c) Several times a month

2. What format (s) do you provide the information in?

Charts

Diagrams

Documents

Maps

Pivots tables

PowerPoint

Verbal

3. What is the nature of these requests?  (If possible, please provide examples of each item indicated)

(a) Summary (e.g. totals, averages, status etc.)

(b) Detailed (specific lists, inquiries regarding specific projects, documents, releases etc.)

(c) Operational

(d) Analytical

(e) Other (this may include revisions, merging, editing, publishing, translating, re-formatting, printing etc)

Once you have these in place, you can then begin to write your documents or start developing that training plan.

Does that make sense?

What do you think?

How can I improve this plan and make it better?

Downloads

Business Requirements Template

Functional Requirements Specification Template

I’ve used the same technical writing tools for the last 5 years. A few products have come across my desk but nothing that really blown me away.

Here’s a run-down of what I use to write my technical documents. No order of preference. Which should I keep? Which should I replace?

Microsoft Word

90% of my technical writing is in Microsoft Word. Like it or not, this is the most popular technical writing tool on the planet. Adobe FrameMaker might get the kudos but Word is what most all engineers, testers, and other contributors use to write docs.

This is the one technical writing tool that I can’t live without.

Could you?

Adobe FrameMaker

Perfect for ‘long documents’. I had Adobe FrameMaker for years before it finally crashed and that was my laptop’s fault. It’s hard to beat on stability but the user interface is a dog. This is ideal for complex ‘books’ with graphs, tables, and diagrams. Unlike Word, it retains the settings and the master templates are a joy.

Downside?

Hard (for me) to customize as I would wish and importing/exporting documents, even to PDF, can be problematic. You would think Adobe would have ironed out these areas buy now…

Camtasia

I use this for creating movies, tutorials and other type of screen recordings. Techsmith products are a delight and this is no exception. It lets me make movies say of an application, add sound, annotations and then export it to HTML or Flash. Arguably my fav tool. Wish I had more reasons to use it!

Snagit

There are other cheaper and free screenshots tools out there but this is the only one I use to taking screen grabs/screenshots. The price is not that much considering how much you get back in return. Also, the folks at Techsmith are very helpful.

What’s so special?

I like the way I can take screenshots with one click (you can add it to the web browser) and then crop, edit and modify the image in the editor. Other features let you batch edit the images, for example, add your website address or add a nice border to all images.

Photoshop

I started in DTP after college so this always has a soft spot with me. Actually, doing the graphics is a nice counter-balance to writing activities. I’ve also found the documents which look nice graphically are more appreciated than plainer ‘image-free’ documents.

Visio

The only tool I’ve used for process mapping and diagramming. Smartdraw is better priced but I know this inside out and can get large diagrams into Microsoft Word (edit, paste special) quickly without destroying the document in the process.

Learning how to create process maps (correctly) was what showed me how this works. Not the most intuitive of apps but wonderful when you get into it.

Epic Editor

My most recent exposure to DITA and structured authoring was with this tool. It’s very unforgiving (unlike Word for example) but once you get the hang of it, you’ll really see its strengths. Expensive but worth the investment if you need a heavy-weight tech authoring tool. Ideal for creating content ‘chunks’, DITA maps and task type information.

Notepad++

Wordpad is fine and I also have also used UltraEdit. Actually, UltraEdit was the best tool I used but it became a commercial tool somewhere along the way (or I kept getting nagware ads) so I gave up and moved to NotePad++.

I like the way it re-opens your last tabs (i.e. files) so you can hit the ground running. The Line Counter is also a nice touch.

RoboHelp

For creating help files and online documentation… well, I want to say that it’s Doc-to-Help as this is what I started with in London all those years back.

Sadly, Doc-to-Help seems to have lost market share and RoboHelp has went from strength to strength. Once Adobe bought it, it ploughed tons of resources into it, aligned it (somewhat) with Adobe FrameMaker and it’s now the defacto tool for HAT.

Or is it? Flare?

Good news!

I’m now working with a client who used Doc-to-Help and may be persuaded to purchase a new license – but it’s not that cheap. Let’s see…

XML Spy

We all get dragged into XML at some point. This tool has a nice UI that shows the tree structure of the tags and how they inter-relate. For someone with zero XML knowledge, this helped me get my teeth the code, create the docs, and get out without mangling the application.

Honorable mentions

• Acrobat
• Doc-to-Help
• InDesign (replacement for PageMaker)
• MadCap Flare and Blaze
• SmartDraw
• Turbodemo (for creating screen recordings and tutorials)
• WhiteSmoke (more for writing business documents)

So, what do you use?

Which of these tools do you think I should ditch? Is there a better tool that Adobe FrameMaker for creating mammoth documents? Or, should I drop Visio and use something open source?

Let me know what you think.

I have a choice. Robohelp or Doc-to-Help? My client has given me permission to use whatever tool I want to do the next batch of tech docs — and they’ll buy the software. No cost to me. Which one should I choose?

Robohelp or Doc-to-Help

Doc-to-Help was the first help authoring tool (HAT) I used in my technical writing career. We’re talking quite a while back now. Since then Robohelp has overtaken it as the tool of choice for technical writers, especially as it’s now owned by Adobe and bundled with its Technical Communications software pack.

For Doc-to-Help

• I feel this product is under-estimated. Other technical writers (more knowledgeable than me about HATs) recommend it.
• Opportunity to broaden my skillsets (self-interest here and not to the client’s advantage!)
• Rapid response from Component 1 (product owners) when I contacted them. Very helpful. Only Techsmith (esp Betsy Weber) were more helpful.

Against Doc-to-Help

• Price is not cheap
• Will there be enough qualified Doc-to-Help experts to take over this project when I move on?
• Does it integrate with other technical writing apps and/or Microsoft Word?
• Worried about lack of community support, i.e. from other technical writers, if I need help.

For Robohelp

• Oceans of Doc-to-Help experts to take over this project
• Part of the Adobe Tech Communication suite. Maybe get discount.
• Arguably the industry standard
• Plenty of tutorials online if I get stuck

Against Robohelp

• Price
• Concern that there is no real advantage in getting the Tech Communication suite anyway as we (i.e. the client) won’t use it once I’ve left
• Found the user interface horrible to work with last time. Admittedly, this was four years ago but you know how these things stick.

Another alternative is Madcap Flare.

What do you think?

If you were in my shoes, what would you do?

Image: Wikipedia

Master templates let you control the format and positioning of every component in your FrameMaker documents. They are very powerful when they work correctly, but be careful. If you make a mistake, it will take many an hour to clean the documents.
[ad#adc-2]
In plain English this means that if you setup a footer as Arial, size 10, and then apply it to the main document, all footers will appear in this font and this size. Sounds good!

But, what if you wanted to have different footers in the document?

You could hard code every footer.

Hard code means you manually type in the footer. That’s ok for a 5 page document but not if your creating a 250 page user guide.

You need to automate the process, which is where master templates come in.

In FrameMaker, you can create different footers, identify each type, and then apply them where you wish.

You can have different headers and footers for the:

• Cover Page
• Table of Contents
• Index
• Chapters, and
• Copyright pages.

Problems with Master Template

One of the problems I’ve had was that even though I’d created the component, it didn’t appear in the document.

The main reason for this, especially for headers and footers, was that the previous entry was still there.

In other words, you have to remove the previous header and then enter the new one.

When you think about it, it makes sense, but if you don’t know you could get very frustrated.

Tip: Delete the ‘old’ header and insert the new ‘one’ instead.

Workarounds

Numbering chapters, headers, footers, and labels can cause all types of confusion.

One trick I’ve learnt it to cut and paste template settings from a FrameMaker document I know works into the new document.

1. In the first document (i.e. you know works), open the template settings, and select the section you want to copy.

2. In the document you want to update, open the template settings, and paste where appropriate.

3. Click Apply and return to the main document. Your changes should now be reflected in the second document.

I have to admit this does seem like a lot of effort.

If you know a more efficient way to do this, please add it below.

Links

Adobe Framemaker Templates Tutorials – This Adobe Framemaker tutorial discusses the following topics: Exploring FrameMaker Templates, Modifying FrameMaker Templates, Creating Custom Templates, Using Custom Templates, and Importing Formats from a Template

How to Create a Template in Adobe Framemaker – While you can use the templates provided by FrameMaker or other pre-defined templates available to you, you may decide that you want to create your own templates. When you create a template, you can set up various types of formats based on what the template is going to be used for. For example, you may decide to create a special Title paragraph tag or table format for your template.

Introduction to Adobe Framemaker 5.0 – This is a Basic Framemaker tutorial. Look at the ‘create a new document’ to find out how to work with Framemaker templates.

Mimic FrameMaker’s Memo Template – FrameMaker’s Memo template is a great example of a template that can be used as a fill-in form. The layout and fields are pre-defined and you just need to fill in the details for each version of the document. C’mon, let’s create our own template that works in the same, wonderful way!

One File, Multiple Uses in Adobe Framemaker – XML lets you publish the same content across different media with minimal effort. And with the new XML features in Adobe® FrameMaker® 7.0, you don’t have to know XML syntax to create XML-compatible documents. Once a developer has created the structured applications, you create the content in a template using predefined element tags and save the file in XML format. It’s ready to use in an XML-savvy application or to convert into another format, such as WML or VoiceXML.

Diagrams, charts, and images all serve to enhance academic, business and technical documents. Without them the reader’s attention would flag and their interest wane.

Visual devices, such as screenshots, balance the text to image ratio.

Long pages of dense, unbroken text will scare aware most readers.

Proposals, case studies, user guides and other such material all benefit from crisp graphics. These help to illustrate the subject you’re discussing. And as they can also be used in presentations and web-pages it’s important that you know how to take good, clean screenshots.

We’ve all seen messy screenshots taken in a hurry and shoddily presented. Instead of enhancing the material in question, it makes it look cheap, amateur, and disorganized.

I’d like to share a few tricks I’ve learnt regarding screenshots – maybe you’ll get something out of these

1. Turn on Auto-hide

Use the auto-hide feature in Windows to hide the toolbar at the bottom of your screen.

Screenshots should not show the applications open on your computer.

Instead of cropping these in Paint or another image-editing package, turn on auto-hide. This will automatically hide the toolbar. It also gives you a larger area to capture. This is very useful if you have a small monitor or use a laptop.

- Right-click on the Start button (lower left corner of your screen)

- Select Properties, Taskbar tab, and turn off Auto hide.

The toolbar is now hidden unless you mouse-over this area.

2. Highlighting Actions

Putting images into User Guides and other such material is definitely a step in the right direction. However you can go one better by showing where in the screenshot the activity occurs.

In other words, show the reader where to click or highlight the area you’re discussing.

Don’t force them to scan your image (printouts will be in black and white) for the item you’re discussing.

- Open the image in Paint.

- Select the Line option and choose the second line size.

- Select the Rectangle option and choose Red from the color palate.

- Draw a red rectangle around the active area.

- Paste this back into Word.

Highlighting active areas will enhance your documents, allowing readers to gather information faster and appreciate the quality of your material.

3. Layout trick

You’ve taking your screenshots and placed them in Word. But something’s wrong!

They’re all different sizes. Your document looks terrible!

How can you resize all the images in your document in 1 minute?

You can fix this by resizing the images and giving them a uniform appearance.

Instead of resizing each one manually, use the repeat key (F4) to automate the process.

Here’s the trick!

- Right-click on an image

- Select Format Picture.

- In the Size tab, adjust the Height, for example 7.5 cm.

Tip: The Width is adjusted automatically if the ‘Lock Ration Aspect’ option is selected.

- Click OK.

- Select the next image and click F4.

This automatically resizes the next image.

With this simple trick you can resize all your images in no time!

Ivan

PS – let me know if you have any tips for creating great screenshots

The median expected salary for a typical Technical Writing Supervisor 1 in the United States is $57,580.

The Salary Wizard at salary.com has some terrific interactive tools for finding the base salaries, average salaries, and top paying roles in this field.

They also offer the “Basic Salary Report based on broad national data, reported exclusively by HR depts of thousands of employers from all sizes, industries and locations.”

Although these numbers are based on national data, the results are most similar to the data from companies with approximately 1,000 employees. If your company is bigger, smaller or in a unique industry, we strongly recommend using a premium report to ensure the most accurate answer.”

Based on their calculations, your Estimated Paycheck Results would be:

Bi-weekly Gross Pay $ 2,214.62
Federal Withholding $ 400.23
Social Security $ 137.31
Medicare $ 32.11
State $ 0.00

Net Paycheck Estimate $ 1,644.97

Take a look at the charts over at: http://swz.salary.com/salarywizard/

Ivan