Posted on

Creating Benchmarks for Technical Documents

One of the difficulties in managing a large team of writers is determining the quality of their work. This is more difficult if the teams work in remote offices, for example, in different countries, and you want to get a better understanding of where they are succeeding and falling short.


One way to get some insight into this is to define a set of benchmarks. Of course, benchmarks will not automatically improve the quality of your product, which is a set of technical documents, but should give you some insight into the performance of your team.

Benchmarks should be seen as one tool in your quality improvement program but not a means to an end.

In other words, your aim isn’t to move the scores for 70% to 100%, rather to determine why the team struggles to deliver specific types of content, for example, workflow diagrams with their materials. Once you understand this, you can explore how to resolve it.

Benchmarks for technical documents

  1. Identify areas to be assessed. Agree on the scope of the quality improvement program. For example, it may make sense to start small, isolate one part of the documentation, say the Online Help, and use this as a starting point. After this, you can expand and gradually include all document assets.
  2. Establish scoring mechanism. Some types of documents are harder to write than others. And, some parts of documents are more difficult. For this reason, make sure when you’re creating a scoring mechanism that you factor in the relative difficulty for each piece/type of content. For example, conceptual documentation may require more attention and effort than procedural documents. If you’re using MS Excel to capture the information, consider using weights for different criteria. You can also consider applying scores, for example, 1-5, depending on the depth of information provided.
  3. Establish a baseline. Once you have the first review completed, you should be able to establish a baseline, i.e. a starting point. Use this to compare the quality of work going forward and identify which areas need the most attention. For example, while your team may be doing well overall, it’s possible that one of two areas keep affecting their scores. These are the areas you need to examine and fix.
  4. Provide feedback. You probably need to remind the team that this isn’t a witch-hunt. The aim isn’t to name and shame. Instead, see it as an opportunity for the team to identify blind-spots in their work and also ensure that they can be proud of the product they deliver.
  5. Avoid using metrics to punish writers. Avoid scoring systems that create a league table as writers will see this as a competition. When that happens, writers will engage in CYA tactics and stop helping each other. Instead, focus on how the team is improving and, where necessary, sit with writers who are struggling to improve their numbers. Remember, they may not be the laziest, rather their results may be low as they have the heaviest workload and most difficult materials to document.


Before you start. Do you really need benchmarks to improve the quality of your technical documents? Maybe not. Are there other ways to achieve this?

If you do decide to adopt this approach, weight up the pros and cons first. What do you stand to gain?  What can go wrong? For example, I’ve seen writers, when pitted against each other, stop sharing information and use passive aggressive tactics to undermine other writers. So, it’s not that straightforward.

Benchmarks are only one tool in your quality improvement program. Before you set about establishing benchmarks, identify how this helps writers improve their work – and it should – and give them examples of how other firms have approached it.

Finally, don’t announce this out of the blue. Introduce the idea in advance, canvas opinions, and set expectations.

Posted on

Robohelp: How to Update Text in Different Topics

How do you update all the files in a Robohelp project at the same time?

quality-checksOne of the limitations of RoboHelp is that it’s very difficult to update files across an entire project using the Find/Replace window. This means that you are limited to correcting each page individually. Not very practical if you have several hundred topics in a XPJ project that all need to be updated.

Note: there is an option to file/replace text, and yes you can go into the code, but it’s not the best when you have issues, for example, with carriage returns, rogue white space, and code splitting over lines.

Why would you want to do this?

Let’s say you’ve:

  • Imported several hundred files from FrameMaker and now have to change a product name, version, or other text change.
  • Imported a database document and want to change the database names in all reference pages.
  • Merged several documents into a single document and want to change a word or phrase whenever it appears.

So, how do you do it?

It’s not high tech.

  • Close Robohelp.
  • Open the files in Notepad++.
  • Select Match Case.
  • Replace All.

That’s it.

Go back and open Robohelp. You should see that the files are now updated.

If you use CVS or SVN, remember to do a Commit to save the changes.

Posted on

Mistakes to Avoid when Evaluating Technical Content

How do you evaluate the quality of your documents in a way that’s impartial, accurate, and easy to implement?

Recently we looked at how to create scoring frameworks (usually in Excel) to evaluate and score technical documents.


From one angle, the scoring is the easy part. What’s more difficult is getting people onside.

Encouraging them to use the framework, score correctly, and most important not see it as a tool which will be used to show up their weaknesses.

That’s the usual reaction.

Mistakes to Avoid when Evaluating Technical Content

If I score low, will my position be threatened or my performance reviews be affected?Content

This is a valid question as ultimately writers will be assessed partly on how they score. However, it should only be one factor in their overall assessment. With that in mind, let’s look at how to implement a scoring system that gets accepted, improves quality, and can be scaled.

  • Give fair warning. No one likes to be caught unawares. So, let the writers know in advance that this is on the agenda and you and the team will be working on it in the coming weeks or months. This allows people to see what’s coming and prepare questions in advance.
  • State your intentions. Once the project starts, explain why you’re doing this. Is it because you’ve been told to (not my idea but…) or because you feel the team will learn and benefit from it. Explain why. Give examples.
  • Define the scope. Is everything going to be assessed? Probably not. Identify the scope of the project, ie what content will be evaluated first, for example, user guides, release notes, online or help, and use this as a baseline.
  • Start small. The first phase is really to get the wheels in motion and find where it can be improve. Don’t expect too much from the numbers. It’s also the phase where you try to get the scoring system embedded into day to day operations, so later it’s just another task to be completed.
  • Describe how it works. Walk the team through the process. Show them how scores are awarded, how (and why) weights are applied, and how this will be tracked over time. Why? It reduces fear of the unknowns and neutralizes some of the gossip and Chinese whispers.
  • Don’t work in isolation. Instead of developing this by yourself – and then trying to launch it by yourself – get others involved early. Look for writers who are keen to better themselves, want to learn more, and are interested in expanded their skillsets. These will usually have the drive, energy, and attitude to help you get the system up and running.
  • Dealing with naysayers. Expect resistance. There will always be team members who’ll try to undermine your position, find flaws in your plan (answer: so, how would you suggest we improve it?) and encourage others to do likewise. While this is to be expected, at least to some degree, you may need to talk to team members whose attitude is influencing the team negatively.
  • Explain consequences. Be honest. Scores reflect your performance at work. However, they should only reflect part of your overall performance. For that reason, clarify how this will affect writers, for example, as bonuses are often determined by performance reviews, and what may occur if writers are consistently getting low scores.


Your team is more likely to accept and use the new scoring system if they’re involved from the get go. Let them know why you feel this will help their careers and if they have suggestions on ways to judge the quality of the content.

Delegate tasks so everyone is involved to some degree, for example, creating templates in Excel, adding best practices to the wiki, and updating style guides if necessary.

Posted on

Technical Writing Projects: How to Create Doc Plan

How long will it take to write those documents? How many writers will you need to get it completed? How much will it cost? What’s the delay?


Any of this sound familiar? If you’re new to managing a tech doc dept, you’ll need to find ways to estimate the amount of time, effort, cost, and contingencies that need to be factored into your projects.

  1. Specifications – are the specifications complete? Identify who can confirm if the specifications are complete, signed off, and whether they are likely to change. Working on incomplete specifications is like trying to document a moving target.
  2. Style Guide and Reformatting – what amount of your time will be spent updating the content to align with your style guide, if you have one? This has to be considered if you plan to peer review or update text from another colleague. Re-writing text to align with guidelines and standards is very time-consuming.
  3. Writing – the actual writing may only take 20-30% of your time. The rest is consumed in gathering information, communication with team leads, getting clarifications, and other tasks related to the subject matter.
  4. Peer Review – ideally, everything you write should be reviewed by another team member. If not, get a business analyst or developer to check the accuracy of your material.
  5. Content Delivery – it’s not unusual for writers to write in, for example, MS Word and then copy/paste it into wikis, RoboHelp, or FrameMaker. Why? Two reasons: One, because it may be necessary to deliver the same content as a PDF, on a wiki, or Online. Two, because there may not be a simple way to export the content from one authoring tool to the next, eg FrameMaker to RoboHelp, without tinkering with styles, formats, layout and so on. Many writers prefer to write the raw text in Word and then format in their respective authoring tools. Choose whatever approach is most productive.
  6. Document Impacts – when you update a piece of content, is there an impact of other documents, for example, other installation guides or releases? Does conditional text need to be applied for specific releases?
  7. Access to working software – sometimes you have to get started without having working software in front of you. While this is far from ideal, it’s not unusual to have to write with the understanding that the GUI may change, for example, new fields may be added, and to allow for these in your estimates. However, this stopping and starting will eat up your time as you’ll need to check each release if and where they are new changes and document these.
  8. Access to developers and subject matter experts – while you may be able to understand some parts of the software, for example, how the GUI works, if you need to document aspects of the system that occur ‘under the hood’, such as Java classes, servers, databases etc, you may need to clarify things with the developers or domain experts. Factor this into your workload as getting demos, answers to questions, and reviews all need to be considered. If these people are not in the same office, allow for scheduling meetings and the extra time this may take.

Remember, there is a risk if you start to document too early in the development process, and the specifications and requirements change due to changes in the budget, timelines and scheduling, your estimates will be affected. Allow for this when preparing estimates and give yourself some bandwidth for known unknowns.

Posted on

How to Repeat Actions in FrameMaker


Wouldn’t it be great if there was an F5 button in FrameMaker like the Redo action in MS Word? Yes, I prefer Word to Frame but we’ll get back to that later.

So, if there a way to repeat actions in frame? Kinda.

Here’s how it works.

Let’s say you change some text to bold and want to do the same on the same page. Instead of manually do it – or hitting F5 if such as thing existed – you can

  1. Press Esc.
  2. Press C
  3. Press C again.

That’s it. After a while you get used to it and can redo lots of text superfast.

Actually, there are three different Redos in frame.
  • Esc c c = repeat last font-related (i.e. character tag) command
  • Esc e e = repeat last element command
  • Esc j j = repeat last paragraph related command
Know any other framemaker tips?
Posted on

Checklist: how to proofread technical documents in 15 minutes

You have fifteen minutes to check your technical document before it’s sent to the client. What do you do? Start at one page one and read every word out loud? Maybe, maybe not 🙂

Here’s one suggested approach to proofread any type of document when you’re under pressure.
276 Photos of Japan

Checklist: how to proofread technical documents in 15 minutes

Instead of reading the document in a single review, break it into a series of smaller, more focussed reviews:

  1. Time – give yourself a timeframe, say five minute blocks, then stop. Stretch, walk, and start again.
  2. Checklist – create a checklist of items you plan to review. These include the usual areas, such as spelling but also exceptions and known issues that tend to crop up. One example is language settings which may have changed if you pasted text in from another document. Another is different footers, again if you merged documents.
  3. Specific – check one area at a time, for instance, check the spelling, format, meaning, or structure individually. Don’t try to do all at once.
  4. Tables – make sure they have the correct heading, fit on the page correctly, and have a header column on the following page if they extend to the second page.
  5. Images 1 – check that the image is displayed correctly, for example, if it’s in an anchored frame in Adobe FrameMaker, check that the edges have not been cropped or positioned incorrectly in the frame.
  6. Images 2 – check that the image displays the correct screen, dialog box or component under discussion. It’s easy to import similar looking images especially if you are new to this area. Also, don’t automatically trust what’s in legacy documents to be correct.
  7. Crossreferences – check that cross-references link to the correct text. It’s easy to miss this especially if you test the link – and it works – but don’t check if it links to the correct text. Double-check that you’re cross-referencing to the correct section, and don’t assume existing cross-references are correct.
  8. Brand Names – create a checklist (cheat sheet) with the correct spelling for each product. Then check if these have been spelled correctly across the document set. For example, it’s Yahoo! not Yahoo, and IBM not I.B.M..
  9. Versions – if you’re updating a new document set, make sure that the version numbers for ALL affected products are updated if necessary.
  10. Variables – if you use variables in your documents, for example, in Adobe FrameMaker, check that these are correct and also check if these have been hard-coded by other writers. This can happen if a team writes different parts of the document and someone doesn’t know (and doesn’t ask) how to apply and update variables.
  11. Hardcoding – this is text that should not be hardcoded, for example, variables or conditional text but someone has hardcoded instead. One area to check is hardcoded links, i.e. a link to a specific page number rather than the actual page, which may change if text is added or deleted.

What else would you add?

Posted on

Adobe FrameMaker: 4 Ways to Find and Replace Conditional Text

When it comes to writing technical documents, the ability to create conditional text is one of the main advantages that Adobe FrameMaker has over MS Word.
Outside the Forbidden City, Beijing

What is Conditional Text?

Let’s say you have one document but you want to tailor some content for different readers. For example, you want to add a new warning message, image or instruction that will only appear in the document for the UK market, but not the US.

Conditional text as the name implies if text that appears based on a specific condition, i.e. show this image in the UK docs but hide it in the US docs.

For technical writers, this is wonderful in that it saves you creating two sets of documents. But, there’s always a catch. You need to keep track of the conditional text and update it when necessary. Otherwise, your docs go out of control.

One way to manage this is to use the conditional text option in the Find/Change dialog box.

Find and Change Conditional text

This let’s you find conditional text and then change, edit, or delete it depending on your needs.

You can search for visible (not hidden text) text that has conditional tags. When FrameMaker finds this, it selects the adjacent text that uses these condition tags.

Make sure that the text with the condition tags you want to find is visible.

To find and change conditional text, do the following:

  1. In the Find/Change dialog box, select Conditional Text from the Find pop-up menu.
  2. To find text with a particular condition tag, move the condition tag to the In list.
  3. To find text that doesn’t have a particular condition tag, move the tag to the Not In scroll list.
  4. To find all conditional text, move all tags to the As Is scroll list.
  5. To find unconditional text, select Unconditional.
  6. Click Set, and then click Find.
  7. To move a condition tag between scroll lists, select the tag and click an arrow, or double-click the tag.
  8. To move all tags from one list to another, select a tag in the list and press Shift and click an arrow.

Note that FrameMaker cannot find conditional table rows.

For me, this is one of the hidden jewels of FrameMaker.

Have you tried to use conditional text in FrameMaker? What problems, issues, or benefits have you seen?

Posted on

Technical Documents: 3 Ways to Improve Quality

Who do you write for? This is a problem for many technical writers, especially if you don’t get to meet or interact with your readers. Essentially, you’re writing in the dark. But, that doesn’t mean you can’t improve the usefulness of the documents. Far from it.
Lovehearts Springtime in Beijing, China

Technical Documents: How to be more accurate

For example, you can work on improving the accuracy of the document in the following three ways.

  1. Provide Context – have you provided enough background information for the reader to understand the concept you’re about to describe? Context provides direction. Think of signposts on a map. Give sufficient information so that the reader can find their bearings and know where this piece of information fits into the bigger picture.
  2. Remove Ambiguity – check if each phrase, term, and defintion is clearly explained. In addition, clarify any points, for example, a type of network setting, that for you is obvious, but for the reader needs to be clarified.
  3. Complete – make sure that you’ve included all items that need to be explained. It’s easy to overlook one item if you’ve focussed too heavily on another area. For example, if the focus during peer reviews was on specific parameter settings, you may have overlooked the database table settings.

These are three ways to get started. What else would you add?

Posted on

A Day in the Life of a Home-Based Technical Writer

Thinking of starting a career as a Technical Writer? I’ve worked in Technical Writing for over fifteen years, mostly as a freelancer. Here’s an outline of a typical day when working from home.

FYI – I wrote this last thing at night, so the grammar may not be perfect. But, it will give you an idea of what’s involved if you’re thinking of moving into technical communications.

A Day in the Life of a Home Based Technical Writer

My day starts at 6.05 and finishes around11pm. I’m online 7 days a week. How do I survive? I often wonder, myself…

A little background

I’ve been in technical writing for 15 years. I remember when Windows was just, you guessed it, little windows. I started with Aldus PageMaker, before Adobe bought it, and then moved onto Corel and other DTP packages.

After leaving theUK, I moved toSacramento, different parts ofCalifornia, then back toAmsterdam,Dublin,London(again), thenShanghai, and nowBeijing. I also work inIreland.

Ok, so that’s me.

Technical Setup for Writing

Technical writing in your pajamas. Well, maybe not actually in my pajamas — does anyone still buy these? — I do work from home.

Here’s my technical setup:

  • LG pc – this is souped up to the gills. I have it assembled when inShanghaiand it has oodles of memory, hard drives, etc. It has never crashed!
  • 1st Dell laptop – super large (too big, to be honest) with Visio, Adobe FrameMaker and other tech document stuff.
  • 2nd Dell laptop for light surfing

Finding Freelance Technical Writing Work

How I get work? Three ways: referrals, legacy customers and consultancy.

Tip #1 Long standing customers is where the money is.

Chasing new leads/projects etc is a fool’s game. There may be short term gains, but in the long run (e.g. when a recession kicks in) it’s your ‘old reliables’ that keep things ticking over.

New referrals come in all the time. But these can be problematic. People want, for example, web-based  help  written up.

No problem?

But they don’t have the product ready yet, so you can’t see what needs to be documented.

Or they think the  specs/screens etc may change in mid-project. Will this change the price?

Or they want you to use Flash to develop a knowledge-base. Why not use SQL? They like Flash; it’s cool.

You can waste a lot of time with these type of customers. We call them ‘tyre-kickers’ at home. They want to buy the car, but never get past the tyre kicking stage.

Technical Writing Consultancy

This is a mix. People want advice on tool to use, need a fresh set of eyes to check a document set, interview junior tech writers or partner them on a new project.

This is happening quite a bit.  Say a web developer is going for a project (e.g. bidding for a contract) and needs a web writer/technical writer onboard. I sign up as the partner and do the documents when they come on-stream.

If you link up with reliable partners, this can be a nice little earner. So, what’s my day like.

Home Based Technical Writer- Typical working day


Alarm goes off at 6.00. Snooze. Up at 6.05.

I have 40 min to check email before the family wake up. Remember most of my clients are in theUS, so it’s their afternoon. This 40 min is often the most frantic time of the day. Someone somewhere has a problem – it’s always urgent – and I have less than half an hour to fix it. Once the crew get up, it’s just not possible. We live in a v nice apt — but there is no hiding place.

Check Email

I have 5 email addresses. I get between 40-120 emails per day. The highest was 700 when I got spammed.

  • I check the business emails in order of priority.
  • Business 1, Business 2, and then Business 3.
  • I scan each box, delete  junk, open what’s left. Many of my responses are 1-2 lines.

Tip #2

When writing emails, use numbered lists to break-out the message, e.g.

  1. To convert the Adobe FrameMaker files I need the source files by Tuesday.
  2. I will need the graphics by Monday inTIFformat
  3. It will be ready by Thursday
  4. The price is 300 USD
  5. Who do I invoice? What’s their email address?

When answering emails, use lists to break out each answer. The reason I do this is that people will often answer the first question and skip the others. Then you have to chase them for the other information. Time is money when you work for yourself. Structure your emails so that it’s easier for customers (and potential customers) to give you all the information you need in one go.

Tip #3 – I NEVER check Yahoo or Gmail before the business emails are finished.

Food. Porridge with walnuts & soybean mix to start. A quick look at the clock and I see how much I can do before their alarm goes off.

Tip #4

Many emails are similar.

“I’ve lost a file, can you make a conf call, how much do you charge etc.”

To speed things up, I have a text file (no formatting) with the answers to the most common queries.

This saves hours every month. They all need to be modified to so degree but the bones of the response is there. Fingers crossed that I get the real urgent stuff taken care off before…


Lights on and they’re awake!

As I’m already pumped up (terrible isn’t it?) I rally the troops and get things moving. One of the downsides of micro-managing your business (depending on how you look at it, I guess) is that it tends to spill over to your home life — everything becomes a task, a deadline, a target.  I try to lighten up. Sometimes we’re late for school. It’s fine.

Eat, shower, shave, arrange school bag, find missing sneaker, feed goldfish, coax pet crickets from their sleep/suspended animation and we’re off on the school run. Get back by 8.

School day are long inAsia(7.30 – 4.45 most days) so I get a good amount done. InEuropethis was more of a problem as we had endless teacher training days, mid-term, bank hols etc. Here, it’s go, go, go.


2 coffees, toast, soccer news, yahoo etc and then close them all at 8.15.

I take lots of ‘mini breaks’ thru the day but keep them all to 10 min or so.

Tip #5 Close the web browser and email. Otherwise, I’m peaking all the time. I know myself. Stay focused.


I work in short bursts between 8.15 and 11.

I use an Excel spreadsheet to keep track of my projects. It’s very simple. Nothing fancy. When under pressure, or knowing that I’m sliding, I print it out as a reminder.

“This is what you have to do, Ivan.”

Tip #6 Working by/for yourself is like dealing with a child. You have to be patient and firm. Little treats and threats both seem to works.

And I reward myself!

When things go well I splurge on a book that I usually wouldn’t buy. Steven Pinker, the Language Instinct is my next treat. Expensive over here.

Setting up interviews

I interview people for this site; it’s one of the most popular sections. Low-tech viral marketing.

I enjoy these interactions as it gives me a chance to meet others, by email and Skype admittedly, and get some insights into how they work.

You think you know so much. But then when you talk to others, you realize, there are so many areas you need to catch up on.

Tip #7

I started writing the questions for this interview at 9.25 (Emails took from 7.55-9.15. Much longer than I thought) and finished at 10.10.

But, here’s the thing.

How should I send it to him? Email, word, on the net?

The Word document I used was pretty bland. Ok, but not much else.

So, I spend 15 min formatting the document (actually tweaking my invoice template). Now it looks 10 x better.

Tip #8

If you want to succeed as a consultant/freelancer etc, you have to go the extra yard ALLTHE TIME. There is so much competition out there, you really have to stand out.

My work varies. This week it involves:

  • Writing standard operating procedures
  • Converting documents from Word to Adobe FrameMaker
  • Creating templates
  • Business process work.

Visio is by far my fav tool; creating process maps, state chart diagrams, flowcharts etc is a doddle.

Like I said earlier, I work in short bursts. Maybe 20-30 min and then stop.

It’s important to stand up, get away from the pc and stretch.  Most technical writers end up suffering from lower back, next and eye problems. Which brings us nicely to….


I have a choice: swim or run.

My aim is to burn up 500 calories per day. I alternate between the thread-mill (even though I hate to run) and the pool (where I love the freezing cold water – the colder the better. BRRRR).

Tip #9

Small Observation

Some of my clearest thinking is in the pool. Maybe this is the only time I really can reflect on the business. No questions, phones, to-do lists. I now carry a small notebook and jot down ideas that pop up.

Chris Brogan mentioned that when on a cruise in Mexico, he had very clear insights  into where he should take his business.

So, while I go swimming too get away from work, oddly enough these are often my most ‘fruitful’ hours. But remember: write it down. Otherwise, it’s gone.


This is part 2 of my day; the halfway point.

From here until 4.38 (I leave on the dot) I continue to work on project


I find it hard to kick-start so soon after the gym/pool. To get around this, I do graphic, diagrams, videos  etc. Visual work is a nice counter-balance to the writing.

Tip #10

I know I’m not the greatest technical writer in the world. But my documents LOOK great.

This is something to consider if you plan to go freelance. The accuracy, quality etc of your material is one thing (arguably the most important) but the packaging makes a huge difference.

I’ve seem people’s eyes light up when they saw a really sharp user guide land on their desk.

Tip #11

Use high-quality paper for the Cover Page if you’re going to give it to the boss. Even if you have to buy it yourself, do it. It feels good.

When you’re a consultant, people like to feel you’re worth the money.

Don’t go cheap. You can claw back the pennies elsewhere.


School run. Literally.


Back at the PC.

Work until 7ish or whenever dinner is ready.

Go swim (again) with junior, or cycle, walk, dvd, draw, whatever until bedtime.


Back at the PC.

Work until 11ish.

The last lap is light admin activities, Snagit work, and planning for tomorrow.

I try to avoid writing technical docs late in the evening as it takes too much brain power. The next day, I’m shattered.

Say goodnight to the crickets, gold-fish, lock the door and then off to bed with a book. Tonight I’m reading Margey Allingham, the Coroner’s Pidgin. Wonderful turn of phrase and great story lines.

Check that the alarm is set.

That’s it!

How many hours a day do you work as a freelance technical writer? What’s the hardest part of the job?

Posted on 2 Comments

How To Get More Traffic To Your Technical Writing Blog

To quote Van Halen, ‘everybody wants some.’ And what you want is traffic. Why write a blog if no-one visits, right? I have 17 technical writers’ blogs in my Google Reader & RSS feeds. Most are fine but… if they used some of the following tactics, they’d get more traffic, comments, money and Nobel prizes. Well, three out of four, anyway.

How To Get More Traffic To Your Technical Writing Blog

Apply five of these tactics and your traffic will double. No kidding, it will!

How To Get More Traffic #1: Add Your Photos

Look at your favorite technical writing blogs. How many faces do you see? Why are they all hiding? I dunno. Stick your mugshot on the page so we can see what you look like! Go on! None of us are Brad Pitt or Paris Hilton, so add a picture. Don’t be shy. People like to read about people they know. If they can’t see you…

How To Get More Traffic #2: Video

I’m no spring chicken, so if I can do it, you can. All of these video were taken on a Canon powershot.

Videos let people hear you, see your expression, feel what you’re trying to say in ways that words cannot. Making videos is easier that you think. I use Camtasia 6 for all its sins. (read my frustrated Camtasia 6 review here.)

How To Get More Traffic #3: Social Media Outposts

Use Social Media for maximum impact. With web content publishing tools like Posterous you can get the message out to all these channels with almost no effort. Posterous lets you post once, publish everywhere. Try it.

How To Get More Traffic #4: Quizzes

We all get tired of checking for split infinitives and looking for typos, so lighten things up. Add quizzes to get people involved… and try to be a little different.

  • Did you ever download software illegally?
  • What’s your manager’s most annoying habit?
  • Would you let your boss friend you on Facebook?
  • Do you know any technical writing who can reverse park? (I was going to say Women but then turned on my brain! That was so close!)
  • Do you know any men who ask for directions when lost? One for the girls, no doubt.

How To Get More Traffic #5: Comics

May not work for all sites but comics are a nice break from technical documents and other heavy reading. Why do you think they are so popular? Every serious newspaper has them, why not you?

How To Get More Traffic #6: Reviews

If they come to your site, it’s your opinion they are after. So, why don’t you give it?

#1 cardinal sin of most blogs is that they have no opinion!

Don’t be scared! I’m with you! Give your honest opinion (try not to rant or swear) and you’ll see people will respond very quickly.

#2 cardinal sin of most blogs… bland!

If your blog echoes the rest of the crowd, well, why should I come back? Stick your neck out, even a little. Some people were upset that I dissed Camtasia but y’know I’d be lying if I said it worked!

How To Get More Traffic #7: Trends

Pssst! Did you know that… everyone wants to be in the know. Keep your readers up to date. Use graphs, charts and diagrams. See Brain Solis and Information in Beautiful for inspiration.

How To Get More Traffic #8: Lists

It doesn’t have to stop at 10. Here are a few list of get started:

  • 21 Left Handed Technical Writers
  • 7 Reasons Why Adobe FrameMaker Sucks But You Still Need to Buy It
  • 12 Honest Ways to Get a Pay Rise
  • 5 Ways To Give An Honest Appraisal
  • 28 Ways to Proofred a Technical Documant
  • 1 Good Reason to Join the STC
  • 18 Mistakes Technical Writers Make Before Breakfast
  • 9 Ways to Evaluate a Help Authoring Tool

How To Get More Traffic #9: How-to guides

Ok, the technical stuff comes last. If you’re going to offer technical advice (and you should!) identify the problem, explain how to fix it, and then ask for questions or comments.

#3 cardinal sin of blogging is… blogger doesn’t interact with readers. Ask for comments. If you have a Facebook page, give them the link and connect there. Use Twitter? Create lists for technical writers and add them. Like these lists I created for technical writers and creativity.

Share, share, share!

What ya think! Fire away below.

Posted on 5 Comments

Review Camtasia 6: The Good, Bad and The Ugly

I upgraded to Camtasia 6 at the weekend (from v4) mostly to import and edit .MOV files. These are created by my faithful Canon Powershot when I shot videos. Sony makes AVIs. The other reason was to do more heavy lifting with Camtasia. I have tons on material on the hard-disk and want to get these into screencasts. So, what the verdict?

Review Camtasia 6

Price – $149 not cheap but not as expensive as Adobe Premiere.

Key features

  • Import and edit MOV files
  • Independent audio edits (saves me doing audio in Audacity)
  • 3D tilt (can’t find where to do this, yet) and oodles of
  • Special effects

The good – What I liked

The user interface is nice, no nutty changes a Ia Microsoft Office and ribbon bars

Presets for blog, YouTube etc means it will help you produce files that best suit these formats. For simple videos, this is fine. You can do your own monkeying around as well, e.g. change frame rates.

the bad – What I don’t like

Audio enhancements are hit and miss. Sometimes makes the voice lovely and rich (hey, why not!) other times I sound like I’m under-water.

Number of un-dos seems limited. I love to un-do.

the ugly – real Problems

Freezes with files over 4 MB. These are (for me) small files, so I need to reboot all the time. Big problem. (What memory do I have? 80 GB of hard disk and 2 GB of RAM – thought that would be ok.) This is a killer. Files more than 3MB cause Camtasia to freeze. What this means is that when I try to make an AVI, MP4 or MOV for YouTube, the thing locks, usually at 19-25%. Close all apps, re-boot and try again. No joy.

Smartfocus won’t start – Camtasia thinks I’m using an older version, e.g. v5, and so won’t start it. I’m on 6. Can’t get it to work. See the error message.

MOVs won’t import – this is a horror! According to the site ‘Large MOV files not importing into Camtasia. Camtasia will crash or give a no codec message upon importing. This is a known issue that will be fixed in a future release. As a workaround, try creating smaller MOV files from other programs when bringing them into Camtasia.’ I’ve done this and still no luck. Off to contact Tech Support.

MP4s won’t import – No Codec available error message. Contact Tech Support.

FWIW I download all the codes I can find on the site, re-boot and… no joy.

What to do next?

Not sure. Have downloaded all the codecs I can find, re-booted the pc, cleared the cache, closed all apps and sent some emails to Techsmith. Now, I’m waiting…

Can you help?

If you’ve had these type of issues, can you let me know what you did to fix this?

Posted on 2 Comments

12 Steps To Getting Started as a Consultant

Most people think it’s difficult start a career as a business consultant. I used to think the same in my early 20s when I started in IT. In retrospect, I should have made more efforts to establish myself as a consultant earlier; the benefits certainly outweigh the downsides. As luck would have it, I was forced into a consultancy role when I lost my 9-5 job. Time to learn to hustling and bring in business. Harvard Business Review refers to it as The Hustle Strategy. More on that later. Continue reading 12 Steps To Getting Started as a Consultant

Posted on 2 Comments

Writing Technical Documentation for Japanese Readers

Carsten Mende explains how loan words are used in China and Japan. These are English words that are commonly used in everyday Chinese, (i.e. loaned) but may not translate correctly if taken literally. He looks at how the ‘Chinese and Japanese languages incorporate English terms and how they are used’ and gives suggestions on what to avoid when translating documentation into these languages.

Difference between English, Chinese and Japanese syllables

He starts by showing the different between how syllables are created in these languages. And as someone who has studied Chinese for a few years, it’s both fascinating and frustrating. Oranges and apples, so to speak.

Latin – allows ‘numerous variations for combining letters and the amount of syllables is extremely large. English has more than 11,000 syllables.

Chinese and Japanese is very different: Chinese (Mandarin) is written in characters; each reflects a syllable and not a single letter.

Adopting loan words in Chinese and Japanese

He shows three mechanisms for the adaptation of English words in both languages:

  • Phonemic way
  • Semantic way
  • Adaptation without any transformation

For example: Coffee 咖啡 ka fei


He cautions that when translating or transferring into a foreign language, ‘even obvious things may shape up as something completely different. So you should always treat your customer attentively, take him seriously and be prepared to communicate in his mother tongue.’

Read Carsten Mende here


The quality of technical documentation in China is often very poor. It’s not for lack of trying, rather they lack experience technical writers and have had little exposure to international audiences.

For foreigners this represents a huge opportunity. Technical writers who can come to China and test the waters could do very well. The pay is increasing all the time and the cost of living significantly lower than elsewhere.

Fancy moving?

Posted on 5 Comments

How Social Media Will Make You A Better Technical Writer

twitterGina Blednyh launched the Technical Communication 2.0 group in Facebook in 2009. It explores the interplay between Web 2.0 and technical communication. It’s a terrific place to exchange ideas about collaborative technologies and new approaches to delivering information.

In this interview, I ask her how Technical Writers can use Social Media and the types of content they are likely to deliver.

How Social Media Will Make You A Better Technical Writer

Ivan: Could you tell us about how you got started in technical writing?

Gina: I majored in English, but prior to that I worked for a software company. The field just seemed like an excellent fit for me.

Ivan: You’ve setup a new group for technical writers on Facebook. Could you tell us about this group? How does it differ from a BBS, for example?

Gina: Truthfully, I never participated in a BBS, though I used to lurk. For me, one of the primary differences is the openness and ease of use of a Facebook group–it’s not “just for geeks.”

Since I just began the Technical Communication 2.0 group recently, I’m not sure yet if it’s the best way to go. For example, perhaps a group on another social networking site would be more effective. But we’ve had some good discussions already and people are posting useful information.

Ivan: Brian Solis recently said that Social Media will soon become Media. It will no longer be seen as a fad. What impact will Social Media have on how technical writer work?
Gina: Wow–this is a big question! And folks far more knowledgeable than me can provide a better answer. My take is that we technical writers might need to abandon certain ideas of who participates in developing good documentation.

We might also need to expand our ideas of where technical documentation resides.  For example, a community centered around a product might include documentation, conversations between users, and feedback (positive and negative) from these users about the documentation. I don’t see this as “bad” for technical writers, however.

If a community includes both positive and negative comments and is well managed, the result can be more customer satisfaction and far better material. I don’t believe that traditional Help systems and documentation will go away entirely, though.

Ivan: What other technical writers inspire you or help give direction to the way you work?

Gina: I’ve been lucky to work with some wonderful writers and mentors! The ones who inspire me actively engage with the profession but also think about opportunities outside of it.

They embrace change and think about ways that technical communicators can better partner with other departments. Basically, they look forward and don’t waste time reminiscing about how things were done “back in the day.”

Ivan: Looking into your crystal ball, how do you see technical writing changing in the next five years?

Gina: Oy Vey! Another big question! I do see technical communicators producing more videos. And in general, I think that we will need to embrace the “technical” part of our job titles more than ever. Offering specialized knowledge will likely be an important quality to offer employers.

Technical Communication 2.0

You can find Gina in the Technical Communication 2.0 group in Facebook.

Your Thoughts?

What do you think? Does Social Media pose a threat to the future of technical writers or can we use it to our advantage? Share your thoughts below.