Author: shaun

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.

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.

Welcome to the Shoap Technical Services blog. Our team will be commenting on business, technology, and, of course, technical writing from our own unique perspective as consultants in the high-tech world.

A couple of interesting links from my bookmarks in the past few weeks:

• Old Meets New – Apple created the user documentation for the iPhone using FrameMaker 6, which was released in 2000. Interesting, as FrameMaker 6 is still one of the best, most robust tools in our arsenal here as well. (via DaringFireball)
• Give ’em Something to Talk About – On creating products that people will talk about: “When people with different opinions compromise, they meet in the middle, not at the edge. But the edge is what sparks conversation.” (via Signal vs. Noise)