Archive for August, 2010


Visio: Fuzzy text, part two

August 31, 2010

Last month I wrote about how to save a Visio diagram so that the text remained crisp. The bottom line was to save the image with a 600 dpi printer setting.

That was the ‘quick and dirty’ version. Since then, I’ve done some more testing using a flowchart created in Visio 2007.

My aim was to save the Visio diagram in a format that had:

  • crisp and clear text when displayed on screen in a Word 2007 and/or PDF document
  • crisp and clear text when printed on a color or black and white printer
  • a small-ish file size
  • applicability across many graphics software applications.

In other words, I wanted the best possible text quality with the smallest possible file size. And the image had to be able to be edited in commonly available graphics software.

Based on my previous experiences with graphics formats, I expected saving as PNG to give me the best of all those worlds, but the reality was a little different! GIF actually turned out the best.

Here’s part of the flowchart I used as my test piece; notice there are some drop shadows, various colors and gradients used for fills, colored connectors, and some basic flowchart shapes:

In my testing, I used my previous findings to set the DPI to 600, where that option was available. I also used an external application (Microsoft Office Picture Manager) to reduce the image size. I then tried saving the Visio diagram in various file formats suitable for a Word 2007 document. I did not test saving as a TIF, EPS, BMP etc. as the file sizes are way too big — I limited my testing to GIF, JPG, PNG, EMF, and PDF (then further cropped and saved to PNG, GIF and JPG from the PDF).

My test results showed that saving as GIF at 600 dpi, then reducing the image size to 25% and inserting the image into Word gave me the best results that met all my criteria. Here’s a summary (click on the image to see it full size):

Some notes:

  • EMF was a distinct possibility until I found that it can’t be read/edited by many graphics software applications. This was a limiting factor — the file format needs to be as versatile as possible.
  • Any format that had a saved size greater than 1 MB was eliminated. My client has very large Word documents with many diagrams in each. If each diagram or figure is greater than 1 MB, the file size blows out dramatically (one of the Word docs I’ve had to work on is more than 150 MB!).
  • Fuzzy text (on screen or in print) was a no-no, and formats/resizes that made the text fuzzy were eliminated.
  • When I did my final assessment, I looked at all those that got a GOOD rating, then compared their file sizes. I then chose the GOOD one that had the smallest file size — GIF, at 600 dpi, reduced to 25%, with a saved file size of 204 KB.

Please note: These tests were done on a single flowchart from my client. I cannot guarantee that my recommended result will suit your Visio diagrams.

Below are the instructions for my recommended method for saving these types of Visio flowcharts.

To save the Visio diagram as a GIF (no top/bottom text)

  1. Click and drag your cursor around all objects, except the top and bottom text objects. A green ‘border’ should surround the selected objects.
  2. From the menu, select File > Save As.
  3. Select Graphics Interchange Format (GIF) as the file type.
  4. Click Save.
  5. On the GIF Output Options window, go to the Resolution section and select Printer (this changes the dpi to 600). Don’t change anything else on this window.
  6. Click OK.
  7. Insert the image into the Word document OR resize it (see below) then insert it.

To resize an image using Microsoft Office Picture Manager

  1. In Explorer, right-click on the image’s file name.
  2. Select Open With, then Microsoft Office Picture Manager.
  3. In Picture Manager, select Picture > Resize.
  4. Select the Percentage option in the task pane.
  5. Change the size to a lower value (e.g. 75%, 50%, 25%). Don’t go lower than 20% otherwise the image becomes fuzzy.
  6. Click OK.
  7. From the menu, select File > Save As.
  8. Give the resized file a new name — don’t overwrite the original!
  9. Close Picture Manager — you may be warned that you haven’t saved your changes (you have!). Click Don’t Save.

(You can use any graphics editor you have — I was limited to Picture Manager on the machine where I was doing this testing. Picture Manager works fine, but you may have graphics software that you’re more familiar with or that’s more powerful — if so, use that.)


Word: Assign a keyboard shortcut to a task

August 30, 2010

I’ve given instructions before on how to assign a keyboard shortcut for a particular task. However, the instructions below are more generic and show you how to apply a keyboard shortcut to ANY Word task, such as a standard function for which there’s no default keyboard shortcut, or perhaps to a macro you’ve recorded.

Here’s how…

Word 2007

  1. Click the small drop-down arrow at the very right of your Quick Access Toolbar (QAT).
  2. Select More Commands.
  3. Click the Customize button.
  4. On the Customize Keyboard window, select one of the options from the Categories list (1 in the screen shot below), then the select the relevant task from the Commands list (2).
  5. Put your cursor in the Press new shortcut key field, then press the key combination you want to use for this action (3). (In the example above, I pressed Alt and c — you can press whatever key combination you think you will remember easily. Just make sure that it’s not currently assigned to another action by checking the Currently assigned to information below the Current keys box).
  6. Optional: You can save your keyboard shortcut in a specific template. By default, the ‘Normal’ template is selected.
  7. Click Assign (4), then click Close (5).

You’re now ready to use this keyboard shortcut in your document, and in any document you create based on the selected template.

Word 2003

  1. Go to Tools > Customize on the menu.
  2. Select the Commands tab.
  3. Click the Keyboard button (bottom of the dialog box).
  4. Select an option from the Categories list (1 in the screen shot below).
  5. Select an action from the Commands list (2).
  6. Put your cursor in the Press new shortcut key field, then press the key combination you want to use for this action (3). (In the example above, I pressed Alt and c — you can press whatever key combination you think you will remember easily. Just make sure that it’s not currently assigned to another action by checking the Currently assigned to information below the Current keys box).
  7. Optional: You can save your keyboard shortcut in a specific template. By default, the ‘Normal’ template is selected.
  8. Click Assign (4), then click Close (5).

You’re now ready to use this keyboard shortcut in your document, and in any document you create based on the selected template.


The reality of conference calls

August 28, 2010

If you’ve ever moderated or participated in a conference call, you’ll relate to this excellent YouTube video. (Thanks to Sarah O’K for Tweeting it.)


Prioritizing your work

August 27, 2010

When you’re working in a busy technical writing or technical editing environment one thing that will come up is how to set priorities when you have many demands on your available time.

If you’re fortunate, you’ll have someone who is your ‘point person’ for dealing with conflicting demands on your time. Often, that’s your direct report or line manager.

In my current contract, I deal with documents as they come in from the authors, taking into account the authors’ written deadlines. Usually that works fine and there’s no conflict. However, on the odd occasion I’ll get several documents in a short space of time, all of which are due in a similar time frame. If I know that I can’t do them all within the time allocated, I’ll contact my ‘point person’ and she will set my priorities. Because this client has some regulatory demands they have to meet, any document needed for regulatory compliance takes priority over almost everything else — her role is to make sure these demands are met. After she’s set my priorities, she lets the authors know where their document fits in the queue. If an author believes their document takes precedence, they have to discuss it with her — not me. So far, this has worked well. I know what I have to do and the order I have to do it; the authors are aware of where their documents fit; and my ‘point person’ is aware of the various demands on my time from other parts of the business. And I’m not continually interrupted with having to deal with conflicting demands on my time.

But what if you don’t have someone who can set your priorities, and you have to do it yourself?

One method I came across some years ago was documented by Seth B — it might be worth trying if you have trouble managing conflicting priorities; it also puts the onus for the decision back on the managers who handed out the work in the first place and forces them to sort it out:

In a former life I had to juggle multiple projects from multiple people, and indeed, some people who had a lower priority were the loudest.

I finally made a large sign that was titled “The priority order is . . .” and wrote the name of each project on cards that were arranged in priority order (determined by others). That way everyone could see (i) how many projects were in the queue, and (ii) the priority order that had been determined by the higher-ups.

The bottom of the sign said “If you want me to change this order, speak to…”.

When someone asked me to change the order, I would pull out a card with the relevant boss name and tack it at the end of “speak to…”.

Never argued, just told them that the change order had to come from the boss.

After a while they got the idea.



Policies vs procedures

August 26, 2010

While often stated together, ‘policies and procedures’ are two quite different beasts.

Kathy F, on the STC Lone Writers SIG email discussion group, defined the difference as:

Policies describe what is to be done and who does it.

Procedures describe how it’s done.

She then elaborated further on policies:

Policies are high-level documents consisting of guiding principles designed to influence and determine decisions, actions, and related matters.

A policy states:

  1. What is to be done.
  2. What resources and methodologies are to be used.
  3. But NOT how to do it (that’s the role of procedures).

A policy:

  • Provides a framework of principles and constraints to be followed in decision making.
  • Guides the organization toward a consistent pattern of decisions and direction of thought (implies latitude for discretion).
  • Leads to (and may specify) planning, actions, and controls for implementing decisions.

Effective policies:

  • Should clearly reflect objectives and plans; mandates set forth in the policy must be capable of being accomplished.
  • May only contain direction with which compliance is mandatory.
  • Should describe criteria for current and future action.
  • Must be understandable.
  • Must be consistent.
  • Should be sharply distinguished from rules and procedures.
  • Should be viewed as subject to change.

For example, a company’s annual leave policy for employees may state:

“Full-time employees are entitled to four weeks annual leave per calendar year. Leave cannot be accrued. Applications for annual leave must be approved by your manager.”

The procedure will describe the ‘how’ of this policy, and may include the ‘who’, ‘what’, ‘when’, and ‘where’ as well. For example:

  1. At least one month before you require annual leave, complete an Annual Leave Request Form (available from [link to company intranet]).
  2. Complete all required fields, making sure you clearly indicate the start and end dates of your leave request.
  3. Press Submit. The electronic form will be forwarded to your manager for approval and sign-off.
  4. Once approved, the electronic form will be forwarded to HR for their records, and a copy of the approved request will be emailed to you.

Other procedures in the section on Annual Leave may describe exceptions. For example, what to do if your manager is unavailable, what to do if your application is refused for the dates you requested, how to put in an urgent request for leave, etc.


Let me show you the ways…

August 25, 2010

Software applications, whether computer- or web-based, typically have several methods you can use to accomplish the same task. If you need to save your work, for example, you might be able to do any of these — or more — to perform that function:

  • Click a toolbar icon
  • Select an item from a menu path
  • Click a command button
  • Right-click and select an option from the shortcut menu
  • Press one or more keys
  • Plus any variations of these for mobile and small form factor devices, such as iPads.

So, when you’re documenting an application, how do you deal with all these options?

  • Do you pick one method and stick to it throughout?
  • Do you list every possible method?
  • Do you mix them up?

My preferred method is to pick one and stick to it. For installed software, I tend to describe the menu path. Occasionally, I might also list the key combination in parentheses after the menu path; for example, ‘Select File > Save from the menu (or press Ctrl+S).’

I also think it’s important that the reader knows there are alternative methods they can use. So I might include a statement in one of my ‘About this Help’ topics similar to that below:

Often, there is more than one way to perform a function. For example, you may be able to use the menu, use a toolbar or toolbox button, right-click on an item and select from the shortcut menu that pops up, click on a unique button, or use a combination of keystrokes. Throughout this manual we have tried to show only one way of performing the function – usually the quickest way. However, you can use any one of the other methods. We have not documented all methods that you can use for a single function – this is to prevent confusion and ‘information overload’.

However, the problem with such a statement is that it may never be read as it’s hidden away in the Help, and not shown at the ‘point of need’.

What do you do? I’d really like to hear your opinion on this as I believe it’s an issue that faces technical writers every time we have a new application to document, and I don’t believe that there’s a single ‘right’ answer.


Dealing with a developer who wants to edit your grammar

August 24, 2010

I cannot take credit for this (and I’ve never used this technique), but I’ve kept it for many years and it’s time to recycle it to a new audience.

[Many thanks to Jeff L on the STC Lone Writers Special Interest Group email discussion list for posting his response to a developer some years ago. Names have been changed.]

I work with a developer who enjoys the belief that he is God’s gift to clear technical writing.  In our open cube environment, he sits right next to the Development Manager.

The other day, after reviewing his comments and deciding that I could no longer use them, I grabbed a chair, walked over to his desk, and sat down.

Smiling, I said, “Hey, John, how’s it going? Great, good, good! Say, listen, I wondered if you’d let me take a look at some of the most recent code you’re working on.”

Mildly baffled, he pulled up his latest project. I began to correct the project (“Don’t you think this should be pulled into a subroutine?” “I’m really surprised that you haven’t used a global variable.”)

Needless to say, since many of my comments *sounded* OK, but were totally lame, he began to get a little ticked off.

Finally, he stopped me and said, “Bill, what exactly do you think you’re doing?” (Yes!! My opening!)

“John, you’re always kind enough to use your skills and background to help me manage technical content, and to help me with organization, syntax and style.  I thought I would repay the favor and help you with your own work. Even though I’m not a professional programmer, I know I have a good feel for the way that programming should work and for the way that programming syntax should appear on the page, so I felt sure I could help you, just as you’ve been helping me.”

There was a moment of silence, then I heard somebody repressing a chuckle — it was Dave, our Dev Manager.

John hasn’t bugged me with unwanted content edits since that time.