Posted on 4 Comments

Favorite 10 Technical Writing Tools

drinking sheepI’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?

Continue reading Favorite 10 Technical Writing Tools

Posted on 18 Comments

Robohelp vs Doc-to-Help? Which is best for Online Help?

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?

Posted on

Create Greek Dummy Text in Word

Lorem Ipsum as four segment DataMatrix
Image via Wikipedia

Lorem Ipsum is dummy text that has its origins in the printing and typesetting industry.

It has been the printing industry’s standard dummy text since the 1500s, when a printer took a galley of type and scrambled it to make a type specimen book.

It came back into popularity in the 1960s with Letraset sheets which contained Lorem Ipsum passages. Desktop publishing software like Adobe PageMaker including versions of Lorem Ipsum as does Microsoft Word. Continue reading Create Greek Dummy Text in Word

Posted on

Word To Framemaker Tutorial

Many tech writers have had to convert Word documents into FrameMaker. It is a very unpleasant and painful process!

The good news is that Tech Knowledge offer a nice tutorial that explains how to convert documents as quickly and efficiently as possible.

“The infamous Word2Frame document describing tips and techniques for converting from Word to Frame or Frame to Word. At the end of the file is a Word 97 macro you can use (on a MIF) to change the first line of tables to a heading row.”

The site also offers a Web-based help system for FrameMaker.

Go to http://www.techknowledgecorp.com/tips.html

Posted on

What exactly do technical writers do?

Technical writers write technical documents that explain complex issues in simple, plain English.

Technical writers – also know as Technical Authors or Information Designers – write material that supports software and hardware systems.

They design, write and produce material that is delivered in print, soft-copy or as Online Help, such as that found in the Help section of programs like Word.

Posted on

How to Interview Tech Writers

Jane R. in Texas asks for some tips on interviewing tech writers, especially when using assessment tests. Her company is about to hire their first full-time writer and they have not done this before.

I’ve worked on both sides on the fence in the past, (i.e. interviewed and been interviewed) and picked up a few tings in the process. Hopefully, these will be of some help.

How much time should be allotted to complete the assessment test?

I’d suggest one hour. Some people will race through it, while others will deliberate over the grammar questions forever. Nonetheless, one hour should be sufficient time for them to complete the test. By allocating this amount of time to the test, you are also emphasizing its relative importance. If it were a simple 10-minute quiz, it wouldn’t carry the same weight.

Here’s a suggested approach for administering the test:

When advertising the vacancy, mention that an evaluation test is part of the assessment process. By saying this upfront, you will ‘weed out’ under-qualified writers who know that they would not pass the test.

When scheduling interviews, remind the applicants that there will be a 1 hour test. Explain to them what this entails, for example, that there is X number of questions on grammar, procurement, technology etc. Among other things, this illustrates your company’s professionalism as you are helping the applicants to prepare for the interview.

In turn, it would be unprofessional to spring the test on applicants when they turn up and catch them by surprise. Completing the test take about 90 minutes and some of your applicants may have other arrangements to consider, such as day-care, commuting etc.

When they arrive, I’d interview them first and then do the test. If they are unsuitable for the position, you can cancel the test and say that it’s not necessary at this point. For those who are suitable, I’d do the following:

  • Give them a pen and paper (always helps).
  • Glass of water/coffee.
  • Find a quiet room with a PC or laptop.
  • Give them a printout of the test (most writers like hardcopys).
  • Walk through the test so that they understand what’s required. They can ask any questions at this point.
  • Once they are ready, leave the room and let them do the test in Word.
  • After 20 minutes, drop in to see how they are doing. This is not to police them, but to see if they genuinely need any assistance.
  • After 60 minutes return and print out their test.
  • At this point, I’d suggest that they have a break so that you can score the test.

Once you’ve completed this, sit down and go over the scores. As everyone likes to know how they performed in a test, I’d walk through the results and discuss them with the applicant.
For example, if they scored poorly in one section, ask them how this area could be improved.

And finally, I’d thank them for taking the time to do the tests and hope that they’ve gained from it.

How many points for a passing score?

You could use 40 for a pass and disqualify anyone who comes in below this. Most experienced writers should get between 60-80 depending on their skills.

What I’d look for here is an imbalance in the scores. For example, if someone failed most of the grammar questions, but did very quite well in other sections, discuss this with the writer.

You may discover that many writers have no formal writing training and will suffer in the sticky grammar questions but compensate in other areas.

I’d use the scores/results to assist the overall interview process, i.e. you have material in front of you that you can discuss with the applicant and explore their abilities as a proposal writer.

You could also ask for their thoughts on this evaluation process and if they had suggestions to improve it. This might give you some insight into writers with potential management or creative thinking skills.

Posted on 1 Comment

Problems with Table of Contents in Word

James in North Carolina asks, “In Word, the Table of Contents is not displayed. Instead, I get an error message: { TOC\O “2-4″\H \Z \T “HEADING 1,1”}. How do I fix this? Is it a bug? “

I think the problem is to do with Field Codes.

Here are three suggestions:

1. In Word, go to Tools > Options > View tab and click off Field Codes (if this is selected)

2. Close Word.
Open Windows Explorer and search for Normal.dot.
Delete all copies of Normal.dot!
Re-open Word.
It will automatically re-create a new Normal.dot, which may be the correct default settings

3. In Word, on the Tools menu, click Options.
Click the Print tab, and then clear the Field codes check box.

Let me know if you know other ways to fix this problem in Word.

Ivan

Posted on

Controlling large docs in Microsoft Word

The main issues with creating long docs in Word tend to involve formatting, styles, graphics, tables, and bullets.

  • Formatting — cutting/pasting material directly from one file into another is best avoided as this will bring unwanted styles in the target Word file. Instead convert it to raw text and then import it.
  • Styles — create specific styles and avoid over-riding settings. Avoid using the default settings in the Normal.com template file.
  • Graphics – avoid using cut/paste graphics into Word. Instead, reference them with Insert Picture etc.
  • Tip: insert graphics only after all other content has been built! Tables — avoid the default Word auto-format settings. Bullets — use styles to create bullets. Avoid using the toolbar and menu options to create bullets. Avoid over-rides.

WARNING: Bullet lists cause more damage than any other feature in Word!

  • Always turn off Allow Fast Save and Save Auto Recover. See Tools > Options > Save > Allow Fast Save.

Developing Microsoft Word files with these pointers in mind will help reduce the file size and avoid corrupting the document template.

Posted on

Why do backward Ps appear in Word?

If you open a Word document and see what looks like large Ps at the end of every sentence, then the Show/Hide marker has been turned on.

Sometimes this gets turned on by accident or when you open a doc which as these turned on by default.

The the Show/Hide marker is used for examining the document’s formatting as it shows details of the underlying paragraphs, section breaks and page breaks.

You can turn off this by clicking the paragraph marker. This is usually located on the toolbar.