Difference Between Run and Execute in Technical Documents

Technical writing is about getting the small details right. The difference between the almost right word and the right word is the “difference between the lightning-bug and the lightning.” Mark Twain So, when writing a user guide, should you say, Run or Execute? From one angle, it doesn’t seem to matter. Everyone knows what you […]

Robohelp: Why Short Topic Names Improve Navigation

The length of the topic title, i.e. the number of characters, needs to be considered when creating topics for online help. Let’s say you’re creating different topics in RoboHelp. Procedures, reference, and conceptual materials. Each of these needs an intuitive and meaningful name. That makes sense. However, you also need to consider the length of the topic […]

User Guide vs User Manual – which is right?

Let’s say you’re setting up a new Tech Docs Dept. You need to create new guidelines, style guides and naming conventions. Should you call the user ‘documents’ User Guides or User Manuals? Which one is right? I was asked this question by a colleague in India who is setting up a Technical Publishing Dept in […]

Detox your Technical Documents; put your Words on a Diet

Goethe once wrote to a friend, “If I had more time, I’d have sent you a shorter letter.” Here’s why.

7 Ways to Improve Your Technical Writing

Here are seven quick tips to improve the quality of your technical documents. When you write a technical document, consider the following points:

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 […]

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 […]

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 […]

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 […]

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 […]