Shoap Technical Services

The second in a series of posts where I pretend to be a programmer.

FrameMaker really shines when you have a suite of large documents that all have to have matching formatting. You create one set of paragraph styles, one set of master pages, one set of reference pages, etc., then you import all the properties from your template into each document, and — Voila! — consistency across all.

In the ideal world, your set of formats never needs to be edited and never varies across your whole suite of documents. Of course, we don’t work in an ideal world, all sorts of things can conspire to ruin your perfect template, and one day you look at your paragraph catalog and you have a hundred styles when you only needed twenty. Maybe some of them came from those times you had to import documents from Word. Maybe others from that time the temp worked on your docs while you were on vacation. Maybe your boss asked for a new style for ideas that aren’t quite Notes but aren’t quite Warnings either.

But now, the only way to get rid of the extra styles is one-by-one using Delete Formats from Catalog. How tedious! And you have to do it for each of your documents, since the import function isn’t destructive.

If only there was a better way …

I’ve been using and enjoying MadCap Flare for a number of webhelp projects lately. I find that it’s superior to RoboHelp in pretty much every way (except for stability and bug count.)

One particularly annoying bug that I’ve found is that Flare, on occasion, decides to insert non-breaking space characters instead of regular space characters when you hit the space bar. The result is that you end up with line breaks in weird and unsightly places when you generate webhelp or printed documentation.

In most cases, the easiest way to fix the problem is to replace all instances of the entity with a regular space character using your favorite search and destroy program. But what happens if you used some of those characters on purpose? I had this problem recently when documenting some XML formats, using non-breaking spaces to indent the lines of sample code.

Since I couldn’t just search and destroy on without losing all of my hard Ctrl-space work, I wrote a script in Ruby to eliminate most non-breaking spaces while preserving the ones I wanted to keep. Read on for more details.

As I learn more about Office 2007, I’ll have plenty of specific tips for you. Until then, I want to provide the best advice ever given to me: Don’t be scared.

Our familiar Word toolbars have been replaced by this:

At first glance it is chaotic and cluttered. Nothing is where it should be. We have no idea what to click. Worse yet, we have no idea what to expect when we actually click something. At times like this, when we are surrounded by the unfamiliar, it is important to remain calm.

If we immediately rush ahead and try to make Word do our bidding, we’re just going to frustrate ourselves. However, if we take a deep breath and examine our surroundings, familiar icons will begin to stand out.

The first thing I’m going to do is mouse over a button I recognize…

…and be pleasantly surprised. Now, not all of the tips you’ll find are as thorough as this one, but many of them are.

Don’t bother typing anything at first. Just take some time and explore the interface. As with all things in life, the more you interact with something, the more familiar it becomes.

1i

P.S., Be sure to note that UFO in the top left is actually a button!

When I broke into this business in the early 80s, my first gig was as a technical writer for a large electronics manufacturer. I had been placed there by a broker (who received a percentage of every dollar I billed). Thus, when I told my manager at the electronics manufactuer that I had nothing to do and that he was wasting his money (development on the project hadn’t started yet), the broker was not terribly happy with me. In fact, he threatened not to pay me for the time I had been there.

From this unpleasant situation I realized that there was an accountablity issue. I felt accountable to the person I was working for — the electronics manufacurer — not the broker who hadn’t a clue what I was doing so long as I continued to bill. And it was at that moment that I decided that when I had my own company, my writers would be full time employees of my company, be accountable to me, and I would be accountable to my clients.

Over the years, this model has worked well. While scheduling can sometimes be a nightmare — making sure everyone has billable time all the time — at least I know and can assure my clients that if there’s nothing for us to at a particular time, we don’t need to be there and come back when there is something to do. This has worked well for my clients (for obvious reasons), for my writers (they feel like they’re always productive) and for me. Mostly, though, it’s just good business.

If ever there was a typo so vile and loathsome that it deserved its own domain, this is definitely it.

Apparently Adobe has gotten serious about changing their mind about giving up on the technical documentation market. After reviving RoboHelp in response to MadCap’s success with Flare, they’ve just now come out with a new version of FrameMaker, the first release since FrameMaker for the Abacus in 208 B.C.

Among the exciting new features in FrameMaker 8: Support for Flash. Which is great, because I’ve been looking for a way to get animated banner ads into user manuals for years.

Here are a few links to some interesting things I’ve read recently that might be of interest to fellow technical writers:

• Web Worker Daily recently published an article on underused (or maybe under-publicized?) Google features. My favorite is Google Alerts – I can have Google send me an e-mail whenever it generates any search results related to a particular keyword. It seems like it could be a handy tool for tracking recent developments related to a certain news story, product, or industry.
• The Photoshop Blog has a really nice posting which links to tutorials for creating several types of text effects using Photoshop or a comparable image editor. This looks like a good place to brush up on some image editing skills…
• DrawAnywhere is a cool web-based tool which lets you draw simple diagrams and charts using nothing but a web browser and an Internet connection. This is something that could really be convenient for any technical writers that need to create quick flowcharts or diagrams while working far away from any licensed copies of Visio.