I know the answer, but I can’t say...

Well, I can’t say it on a public mailing list using my real name, anyway. But it’s too funny not to share.

The following conversation took place on a mailing list I subscribe to. The text in red is from a documentation manager who works for a competitor; text in blue is someone who is trying to be helpful.

Anyone with experience converting from AuthorIT to FrameMaker 7.2?

Did you have any significant problems? What sort of prep work did you do before converting?

Why are you interested in converting from AuthorIT to FrameMaker? I ask because I have just been working in a place where AuthorIT is being considered as a replacement for FrameMaker - is AuthorIT not delivering the goods?

My company uses FrameMaker and may go to XmetaL eventually. We acquired a company that outsourced the doc to a turn-key vendor that does not even store files on our corporate server, let alone use our standard templates, our file management system, and so on. This creates all sorts of problems, including putting our intellectual property at risk, severely limiting our control of resourcing projects, and so on.

At this point, I should mention that I have a pretty good idea of which company it is that got acquired: one I used to work for about ten years ago, in fact — although the outsourcing bit must have happened recently. And so the thread continues:

Thanks! That sort of outsourcing takes a lot of courage, or faith in your supplier, or stupidity!

You can probably guess what my vote would be. I was happy for the employees of this particular ex-corporation to see them get acquired; that’s a place in dire need of a culture enema. In fact, once the enema has been administered, I would consider working for them again.

I thought about jumping in on a thread on one of the other mailing lists that the competitor posted to, where my email address isn’t tied to the company I work for, but I don’t have anything to say that they probably aren’t aware of already — there isn’t a trivially easy migration path. You have to do what engineers call a “double-pump,” convert to an intermediate format that both programs understand, then convert that to your target format. If they are using structured FrameMaker, they could create AuthorIT templates to export XML in a format that their FrameMaker setup could use directly. Otherwise, they should export to Word format, using the same style names as their FrameMaker templates, and expect some cleanup work.

A question that will be harder to answer, but the manager is going to have to ask soon, is “Do we clear the decks of any ongoing work and do this conversion all at once, or convert each document as it’s needed?” There are advantages and trade-offs either way. Doing it all at once means you might miss some deadlines (which tend to slip on their own anyway), and you may end up converting documents that you won’t need later on, but you also don’t need to keep a rather expensive AuthorIT database around. Doing it piecemeal is probably easier, but you have to keep the old rig around (unless you just export everything to the intermediate format and do the second conversion later) and the goal line is hard to see (how do you know when you’re done?).

Such are the decisions a manager has to make. I suppose if I were the one making the decision, I would export everything to the intermediate format, and archive anything not being actively maintained. Then I could decommission the AuthorIT rig and “insource” some writers to import the active projects and get to work.

Don’t force it, get a bigger hammer

I have to confess that many years of using Macs, combined with a monkey curiousity that led to deep familiarity with the platform, has spoiled me: when my computer should be able to do something, I expect it to Just Work because it almost always does. And I get annoyed if it doesn’t.

The latest example began last weekend. Exploring the 43folders site, I found a clever little kit called the Hipster PDA. Like most geeks, I like low-tech when it works, and this is as low-tech as it gets: a build-your-own personal data assistant consisting of a stack of index cards and a binder clip. Sitting in the living room with the iBook, I thought to myself, “I’d like to try that. I wonder if I could find some index cards around here.” Then I glanced over at the lamp table, and lo! a stack of index cards, left there by someone and never put away, awaited. Figuring this was a Sign From Above, I put down the laptop and located a binder clip.

With a place to keep ideas, project tasks, and miscellaneous to-dos, my brain started suddenly remembering things I wanted to do around FAR Manor (and work) at odd moments. I could just whip out a pen and my stack, jot it down, and move on. I wound up with a rather intimidating shipping list for Home Depot, and a longer list of stuff to do around the house than I really wanted to recognize. I soon needed expansion memory (i.e. more index cards), and found the supply cabinet at work has both color and regular cards. Having found a useful way to capture and remember all those little things that could be done later, I started looking at it a little deeper, thinking about accessories (this is how male geeks keep in touch with our inner female: we accessorize our gadgets, not our wardrobe). Oh cool, how about some templates to print on the index cards?

So I downloaded the PDF, grabbed a handful of blank index cards, fired up Preview, and tried printing a few pages. The laser printer dutifully sucked in the cards, and spit them out — still blank. Suddenly realizing I needed to create a 3x5 page size, I did so and tried again... with the same results as before.

I went into full-blown troubleshooting mode at this point, trying all sorts of different things including installing new printer drivers and trying a different printer. Nothing worked, although at one point I managed to get the first two inches of a page to print at the bottom two inches of the card. It got late, and I gave up for a night that turned into a week.

Some time during the week, a thought hit me: if I could get the image to print at the top-center of the page, it should print on the card. I knew of two ways to make that happen — import each image into a page layout program by hand, one at a time, or use good old groff to do it all for me at once.

For those of you who aren’t familiar with *roff or other batch-style formatters, that’s the way most of us produced complex documents before 1990 or so. For books, or collections of books, not even the best GUI programs can yet match the capabilities of groff, and don’t even come close to matching their speed or efficiency. I’ve actually turned back to using groff at work because even FrameMaker is too slow and clunky to do what I need nowadays.

Once I hit on that idea, I had my printed cards in a few minutes. I opened a Terminal window and began the incantations:

$ pdf2ps diyp3h_core_1up.pdf diyp3h_core_1up.ps
$ for (( i=1; i<=84; ++i )); do
> psselect -p${i} diyp3h_core_1up.ps pg${i}.ps
> eps2eps pg${i}.ps pg${i}.eps
> rm pg${i}.ps
> done

Now I had 84 EPS files, one for each page in the PDF file. To do anything with them, I had to create a file of groff commands to put each index card at the top of an otherwise blank page:

$ ls *.eps | awk '{print ".bp"; print ".PSPIC $0";}' >cards.t

I opened the PDF, identified cards I didn’t want to print (and those I wanted multiple copies of), and edited cards.t accordingly. Finally, I stuck the cards in the printer and typed:

$ groff cards.t | lpr

The first couple of cards came out crooked, until I squeezed the paper guides together a little more tightly. My Hipster upgrade was quickly ready; now I just need some time to copy the data over....

Quotable quotes about Word

Another gem dug up in my email clean-out

As technical writers go, I’m relatively lucky. In my 20-odd (and I do mean odd) year career, I’ve only in the last couple of months ran into overload situations that had me working weekends as well as overtime (it’s not uncommon from what I’ve heard from other people). But I’m even more lucky because I haven’t had to use Microsoft Word as a serious writing tool for almost 10 years now. Before that, Word (up to Word 7.0/95) was a decent word processor, not terribly solid (especially for documents longer than 50 pages) but easy to customize, very scriptable and mostly predictable. Being a button-pusher by nature, I was able to find and then avoid the sharp corners and rough edges and get work done.

For people who live in their word processors, Word97 marked a major turn — downward. Corrupted files, always a possibility, became more frequent. Auto-numbering went straight to #3|| and skipped the handbasket. Preference changes would spontaneously change themselves back. Fortunately, about the time Word97 (and Word98 for Macs) landed on the world with a wet plop, I changed jobs and went to work at a FrameMaker shop. Frame isn’t the most feature-laden product in the world, but it is extremely predictable and very stable. The only way to lose significant work to a FrameMaker crash is to start typing in a new document without saving it before it crashes. Anyway, all the things I started hearing from Word users at that point made me less than motivated to go back.

Nothing I’ve heard has suggested the problems are being fixed. In fact, I’ve repeatedly asked a Microsoft program manager who works on Office file formats whether the next version of Word will fix the autonumbering problems that have been around since '98. No response. (Funny how the search function at Microsoft’s blogs.msdn.com couldn’t turn up its own blog address but Google could, by the way.)

So here’s a few quotable quotes about Word that I’ve collected from the Techcomm list....

“First thing I realized about trying to do documentation in Word is that I had to lower my expectations.” — B.A.

“Only entirely random actions, bizarre incantations and forceful oaths can make Word do what you want it to (especially when it comes to numbering).” — M.B.

“Nothing will work in Word if you're wearing the wrong kind of shoes or whatever.” — B.A.

“It's a known Word bug.” — a cast of millions

This profanity-laden rant is also notable, not only for expressing the frustration so many of us have with Word, but for being the only piece of writing I’ve ever seen that manages to use that much profanity and stay coherent.

And finally:

When I first started using Microsoft Word professionally, about 10 years ago, someone told me that the only thing to do to get it to work as you thought it should was to sacrifice a small goat during the correct phase of the moon.

I ran a Google search today on ‘+"Microsoft Word" +"sacrifice" +"goat"’ and got 650 hits, so clearly this belief is now widespread. (OK, so some of the hits were about obscure religions rather than tech writing, but my point is still valid.)

— D.F.

Word does (mostly) well for most people, who don’t need more than 10%–20% of the functionality it offers. It’s those of us who live and die by our word-processing skills who run into trouble with it, because we need to push it to the limit just to stay caught up. And pushing Word makes it tip over, quickly.

Caught in the (first) draft

In an example of synchronicity, articles about first drafts hit both 43 Folders and MacDevCenter today. 43 Folders suggests Just Doing It, while MacDevCenter explores tools (some of which don’t exist yet) to help eliminate distractions so you can focus on writing (instead of editing).

If you read the comments in the MacDevCenter article, you’ll see where I suggest the hoary Unix line editor, ed, for first drafts. It has been part of Unix systems since the first version in 1970 and is still lurking at the bottom of the most modern version of Unix (aka MacOS X). There’s also a neat trick for disabling the GUI at login time, leaving your entire screen dedicated to a white on black console screen: type >console instead of your user name and hit Return.

Now there’s an environment for first drafts: no email, no web browser, no instant messenger; just you, your thoughts, and your keyboard. Going back and editing a previous line is more trouble than it’s worth, using ed (you can backspace though), so you mostly just keep typing until you’re done. Plenty of time to edit later.

Deep techie secrets revealed!

I got several phone calls at work late last week, mostly having to do with formatting and printing the term papers the boys finished up (after pulling an all-nighter). Most of the issues were solved by my telling them to click something or another. The only problem that wasn’t in that category (transferring a file from Mrs. Fetched’s computer to Daughter Dearest’s) could have been avoided by typing the file on DD’s computer in the first place.

Twenty years ago (I tell ya, things were different in my day! Men were men and sheep were nervous! Um...) the company I worked for bought Macs for our department. I admit to being less than impressed with them after the initial enthusiasm wore off — it took several years of improvements for the Mac to first win my respect and a couple more years before I came to love 'em. But I digress. I spent the first couple of days just exploring the menus in various programs, clicking buttons, and generally seeing what I could make the thing do. I ran into things, clicked around until the problems went away, and got confident with its limited scope.

It wasn’t too long before my co-workers ran into the same problems I’d already hit and solved. People would mention off-hand a problem they were having, I’d say, “oh, try this and such,” and it would work for them too. After a few of those, I was suddenly the “Mac Guru” and everyone in the company — including IT — would ask me for help. Since my extension was 4573 and the IT helpline was 4357 (HELP), I’d get wrong-number calls (at first) asking for assistance and then people would start calling me before they would call IT. All because I fiddled around with things.

And that, dear readers, is the Techie Secret. In fact, it’s so much a part of our psyche that we have an acronym for it: PBUSH (Push Buttons Until Something Happens). It’s so simple, and it explains a lot of our frustration with non-techies. We’re not really any smarter (well, not much smarter) than the rest of you, we’re just more curious. Any hairy hoary knowledge we’ve obtained, we’ve obtained the same way any animal does: faced with a constraint, we poke and prod at the door, especially that little latch thingie, until it pops open and we’re free! Over time, we figure out what works and what doesn’t, and we use that knowledge and confidence to attack the next gate. Beyond curiosity, there’s no innate talent — it’s all the kind of skills that anyone can acquire. Why are you calling us when you could just click around and figure out how to fix it on your own, probably more quickly than you can describe the problem?

One of the first questions you’ll hear from a support person, formal or not, is “what have you tried to fix it so far?” If you’ve tried anything that didn’t work, both of you save time because the support person can skip those suggestions. It also gives the techie both an idea of how complex the problem might be, and how involved you’re willing to be in the solution. Every platform typically has a handful of first responses — like fix permissions and run drive checks on MacOSX, rebuild the desktop on older MacOS systems, or reboot and run spyware checkers on Windows — that clear up 80% of the issues. By running these simple maintenance routines, either on a regular basis or when problems crop up, you give yourself a great deal of power over your balky toy/tool, and save time for everyone.

Careful, though — that sense of empowerment might lead you to look into those other problems, the 20% that routine maintenance doesn’t fix. You may find yourself typing error messages into Google to see if there’s any information out there (and often there is). You might start looking at those mysterious programs that came with your operating system and running them just to see what they do, perhaps finding a nice tool in the process. Eventually, when another non-technical friend has a problem, you might be the one to suggest a fix. Before too long, they’ll be calling you.

PBUSH usually isn’t dangerous to your computer, but it can turn you into a techie. Beware.

A good introduction to malware

Current music: #Musik Club

What the heck is malware? Why is it an issue? What other silliness is going on out there? Bruce Schneier writes up a pretty good overview in Wired, Everyone Wants to 'Own' Your PC.

A Tour of Microsoft's Mac Lab

As much as I like to rag on Microsoft, I have to admit that there is a good side to the company... namely, the Macintosh Business Unit (MBU). David Weiss was recently kind enough to give us all a virtual tour of the Mac Lab.

Go check it out!

Amen, amen, and amen

Douglas Crockford hits it on the head talking about “introduction” web pages:

What a Flash intro says to me is "I hate my job. What I really want to do is make films. But they won't let me do that because I don't have talent. So watch this Flash intro."

Web sites end up getting polluted with crap like Flash and JavaScript for various reasons, but perhaps the single most common underlying issue is that “designers” have no content to give you, so they substitute an “experience” for something useful. Yeesh. I don’t spend (way too much) time on the Internet to have an “experience,” I just want to get some information or look at pictures or something. It’s kind of like the now-defunct Damon’s, a restaurant chain that sported multiple big-screen TVs tuned to various games. They billed themselves as “A Dining Event!” I tend to think of a “dining event” as something like that time when The Boy found a dried-up roach in his cereal — I don’t want a “dining event,” I just want something to eat (preferably insect-free). Same with the web: I don’t want Flash and Java$#!+ substituting for content. If I wanted to waste time with mindless garbage, there’s a TV in the living room.

Think of a web site’s “design” in the same way you would think about packaging a product — what you’re really interested in is what’s inside. Apple is widely acknowledged these days (at least in high-tech) as the masters of package design — and guess what? The decorations are muted, even minimal. Even Microsoft (internally) acknowledges that they’re way behind Apple here (and everywhere else IMO).

Macromedia describes Flash as “the solution for producing and delivering high-impact web sites.” High-impact on my bandwidth, CPU, etc. I’ll show you “high-impact,” as soon as I find that sledgehammer.

---

Thanks to Doc Searls for providing both the inspiration and supporting links for the above rant.

Well, I’ve started...

The boss told us in the staff meeting that the word for the year is “automation.” I told him I could automate quite a bit of my work by going to a markup-based system, and he said go for it.

So I’ve stopped talking about dumping FrameMaker for groff and started doing it. Not a moment too soon — the new Intel-based Macs won’t run Classic applications, of which FrameMaker is one. I’m probably going to be getting a MacBook at work soon, and getting one for myself as well.

It helps that the latest version of groff adds support for links and bookmarks in PDFs, and the HTML output continues to improve, so I shouldn’t lose any functionality.

Google-licious

Google is starting to take notice of Mac users, finally. They’ve released three DashBoard Widgets, of which I installed two: the Blogger widget (I’m using it for this post) and the Gmail widget. I had to rearrange my Dashboard a little — the Gmail widget in particular is pretty big, especially for the iBook’s 1024x768 display — but change is good.

Dude... you got a discount

We got a company-wide email a couple of days ago, announcing that we were now part of the Dell Employee Purchase Program (EPP). We can get up to 12% discounts on Smelly Dell consumer models, plus a free download of XP Home.

ooooooooooooooooohhhhh... ahhhhhhhhhhhhhhh

The funny thing is, we’re in a de-Dell-ification process at work; people needing new computers are getting IBM/Lenovo ThinkPads. I’ve suggested to those who are waiting for their Smelly Dells to finish flaking out to “accidentally” drop them on the way to a meeting or something so they can get to the front of the line. Just trying to be helpful....

From experience, when people ask me what kind of computer to get, I tell them two things: 1) Don’t get a Dozebox. 2) If you ignore #1, don’t get a Dell. Then they get a Dell, have all sorts of problems with it, and I get to say I told you so. :-P I’d take one if they gave it to me, but I’d install Linux on it and use it for a music/video jukebox.

I would have been in bed earlier...

...but I found my old website from my Nyx days in The Wayback Machine. The home page proudly states that its last update was November 7, 1998... in Internet time, that’s like gaslight and 2400 bps “high-speed” modems. It even has the lost episodes of Chicken House Hell, which I may scarf up and repost here if I’m feeling sufficiently disgusting. Anyway, I spent way too much time looking at stuff I wrote over seven years ago. I thought I’d had a detailed analysis of the Concept virus there, which is why I tried to find it in the first place, but it either didn’t get archived or I put it on some other page (it might have been an internal corporate site).

If you’ve been around a while, long enough to abandon a web site or two, your old sites may well be gone but not forgotten. If you can remember a URL, punch it in and see what happens.

Now I’m going to bed. Maybe I can get over this and sleep....

The End of Innocence

We knew it had to happen sooner or later: now Mac users have the Leap.A trojan to worry about. Something like 50 people, total, have been hit by this... but judging from the press coverage, you’d think it was Apocalypse Now. Just don’t accept any files called “latestpics.tgz” from iChat and you should be fine.

Way back when transferring files meant schlepping them around on a floppy, Mac viruses were fairly common. I kept a fairly extensive collection of disinfectant software and had a fairly detailed plan for cleaning up the department Macs when we got hit (which only happened twice in five years). Later on, the primary viral focus shifted from floppies to Microsoft Word files; you could write viruses using Word’s macro language, and they ran on both PCs and Macs. I remember the first Word macro virus; it was called “Concept,” and it was simple enough that I took it apart and analyzed it. It was rather chilling to see a routine called “PayLoad,” which contained only the comment “this should prove my point” — and indeed, it wasn’t long before more destructive macro viruses (that mostly only damaged PCs, fortunately for me) appeared.

After that, malware activity on Macs faded away gradually and those disinfectant utilities withered for lack of need. Lordy, it’s been 7 or 8 years since there’s been anything beyond breathless pronouncements, quickly debunked. Part of it, of course, is the sheer number of Dozeboxes in the world... and the larger part is how easily it has been for malware to infest those Dozeboxes. Macs represented too much effort for too little return, so we have enjoyed a long period of innocence which may well have come to an end this week.

If you use a Mac, grab the Free ClamXav malware scanner if you haven’t already. I think it’s already been updated to detect Leap.A, and it’s a good idea to use it if you transfer files to Dozeboxes... you can’t get infected by their viruses, but you can be Typhoid Annie and transfer them. Be a good citizen and avoid doing that.

While Leap.A is probably not a serious threat — you have to accept an incoming file transfer, unpack the archive, double-click the executable (that tries to disguise itself as a JPEG file), and enter your password to allow the installer to do its thing (and if a JPEG file wants your password, it’s probably not a JPEG) — it represents the straggly first weed in your putting-green lawn. Time to get the shovels, rakes, and implements of dee-struction... and keep them safe in the garage. For now.

When Computers Go Bad

Saturday night, Daughter Dearest came in with her laptop and said “it’s doing something really weird: it gets all these pretty colored lines on the screen, then it goes black and freezes.” I held down the power button to force a shutdown, then restarted it. It got to the "Welcome to MacOS X" screen, then did exactly what DD said it did. I shut it off again, jotted down her serial number, and looked it up. Whew, all of three weeks left on the warranty! Thank God it wasn’t three weeks after.

It’s not unheard of in the G3-series iBooks (maybe the G4s too) for this to happen. It’s either the cable the runs from the screen to the motherboard (new cable) or the graphics chips (new motherboard). DD is jonesin’ for her laptop, and using mine some nights (which partially explains why I haven’t updated much this week). The bright spot is that she might get a G4 motherboard out of the deal, a nice little upgrade.

Since she had my laptop, I picked up Bedbug, an old (as in 100MHz Pentium) NEC Versa laptop running Debian Linux. Some time back, it had gone sour after an upgrade, and I’d never gotten around to fixing it. Without getting all geeky on you (that’s coming though!), the upgrade had lost the network (and other) drivers, which turned its network into a not-work. The old kernel (the central piece of the OS) was still on the hard drive, along with its drivers, so I told Bedbug to drop back to the old kernel. Presto! Well, not quite. It now realized it had an Ethernet port, but the hardware was acting like it didn't work right. It might be the cable I was using; we’ve strung it through more than a few doors in its day and it might have finally broke. I’ll try it tomorrow with a good cable and see if it does any better.

...and we got an offer to extend the warranty on DD’s computer for another year, for $148. Mrs. Fetched and I had the same thought: if it flakes out again, we’ll be way ahead on that deal. Now where’s that checkbook....

E-paper becoming feasible?

Category: Technology
Current music: Digitally Imported (DI.fm) EuroDance
According to this article in Wired, Siemens has demonstrated a flexible, ultra-thin, ultra-cheap display technology. Wired’s lead-off is a tad alarmist, though: “The cereal aisle at your local supermarket may soon resemble the Las Vegas strip,” they warn us.

Um, no.

First off, the article quotes several skeptics who question whether Siemens can manufacture the e-paper in quantity. Assuming they leap that hurdle, they’re talking about 30 cents for a piece of e-paper measuring a couple of square inches (or a handful of cm²). The realities of mass retail suggest — no, scream — that when a box of cereal costs about $3 and a can of soup goes for 59 cents or less, adding 30 cents to the per-unit packaging costs will fly about as well as a pig. There might be a handful of special promotional cases, but overall I wouldn’t be concerned about blinking cereal boxes any time soon (where “soon” is 2008 and beyond).

But if the Siemens e-paper idea works out, it could be the final piece of the puzzle that leads to widespread acceptance of E-books. I thought I’d written about this before, but it must have been off-blog. I believe that electronic books will only become popular when the readers are cheap enough to be disposable — selling for $10 in the checkout line racks, for example — and are no larger than a paperback book. The major hurdle here has been the display; they're relatively bulky and too expensive to make E-book readers more than a “bleeding edge” idea at the moment. Take a page or two of Siemens flexible e-paper, put a card slot and some rudimentary controls on it, and you have a reader.

Now watch book publishers try to kill the technology the way the RIAA and MPAA are trying to kill DVD/CD writers....

RTF: the “other” interchange format

Category: technology
MacDevCenter’s Giles Turnbull has an article up on using RTF (Rich Text Format) as an interchange format. For non-technical users, this is probably the best way to move documents around without having to worry about whether someone can read them. Nearly all word processors that aspire to be “full-featured” provide some support for RTF these days, so it’s a good starting place.

This morning at work, I was asked to provide some information from a quick-start guide for a hand-off to a customer (who wants to write some custom stuff). We’re using FrameMaker for documentation, not Word, and Word users just seem to assume everyone else uses Word. Imagine that. (For those who wonder why I don’t use Word, this profanity-laden rant pretty well sums it up.) FrameMaker’s RTF exporter is less than wonderful, producing sloppy text formatting and losing the graphics, but the customer just wanted the tables so it’s all good.

Way back when, I brought RTF home once and used a text editor on an Amiga to make updates to a manual. We had a deadline and a snowstorm, so I wanted to make sure I could hold up my end of things even if I couldn’t get to the office. It worked, except for one minor detail: those spaces at the end of lines of RTF are significant, and my text editor insisted on removing them... so when I got back to work & opened it in the word processor, there were spacesmissing here and there. Running the spell checker fixed all but one or two of them.

So with all these wonderful real-world examples, what’s lacking in RTF compared to ODF, the virtues of which I’ve been extolling lately?

First, RTF has been one of those formats that is supposed to be well-known, but Microsoft has always had a penchant for omitting things. The newer specifications are better.

Second, there are RTF parsers and conversion tools out there, but they are far less well-known than equivalent XML tools.

Third, even Microsoft is moving to XML for document interchange.

RTF, given its Word-driven ubiquity, will be around for a long time to come and will continue to be a useful interchange format for people interested primarily in exchanging and using documents. Many people will continue to use older versions of Word and Office for a long time to come, and XML interchange won’t be feasible for them. But for those of us who want our computers to extract (and perhaps transform) the important pieces of the documents we get, XML is really the way forward.

Laziness and Open Document Format

Categories: technology, work
Current music: Groove Salad
Just before I took off for lunch today, the contractor who picked up the projects I was working on before the reorg motioned me over and asked me, “how did you do it? You put together the whole shell of this project, and I’m just hanging stuff on it. Especially the command-line stuff... how did you get so much of it done with nothing to work with?” Pulling miracles out of my, er, back pocket has been a lot of what I’ve done at the office for the last few years. I got deadlines, limited access (at best) to equipment, a little help from my boss when he’s not swamped with other stuff, very little in the way of specifications, and somehow I managed to maintain documentation for three entire product lines.

My secret is: I’m lazy.

Look, I sit in front of a computer all day. If I can get the computer to do something for me, especially if it’s something that needs to be done more than once, I’ll do it. For example, our original (now “legacy”) product line came with about 4000 pages of documentation scattered over about 20 different manuals. We provided a master index, a 110-page book of its own, as a way to let customers zero in on which manual(s) covered a particular topic. The first time I did the master index, it took two solid weeks of nothing else. This is one of those prime examples for automation: I had to build a book in FrameMaker of all the other books, tag each chapter in each manual, run the index, convert the tags to document references (for example, change “EG” to Engineering Guidelines), remove all but the first reference to any chapter, blah blah blah. To make a long story shorter, I wrote a handful of AppleScripts that eliminated literally 80% of the grunt work: instead of two weeks, I could build the master index in two days. Yesterday, I wrote a script that created index entries from headings (which is OK for a first pass at indexing commands) that saved me a day’s worth of work.

I told you all that to tell you this.

A couple of weeks ago, I wrote about Massachusetts adopting Open Document Format (ODF) for state government documents. Between than and now, OpenOffice 2.0 went into beta test; yesterday, OASIS (Organization for the Advancement of Structured Information Standards) submitted ODF to the International Standards Organization (ISO) for consideration as an international standard for office document interchange.

The neat thing about all this is that the ODF format is easy to pick apart and fiddle with. Internally, content, graphics, and style information are separated and the whole thing is rolled up in a ZIP file. Content and style files use an XML format, which is important for two reasons: XML is plain text, and there are lots of utilities to work with it. So what does that mean? There are several Free programs that support ODF already (OpenOffice and AbiWord run on most computers, while Koffice also runs on Linux systems). But the really fun part is, given a document format both open and relatively easy to parse, you don’t need an office application to do things with ODF files.

In the computing world, when a group like OASIS sets out to nail down a standard, they form a Technical Committee (TC) of interested parties. In the case of the ODF TC, some of the interested parties include companies that make content management systems (or CMS... the alphabet soup is sloshing around quite a bit tonight!) — suffice it to say that a CMS allows you to store, retrieve, and process documents to make something new (kind of like putting basil leaves in a food processor and making pesto). Given the job of a CMS, it usually doesn’t just store a document as-is. In the case of an ODF file, the CMS would probably unzip it and extract just the content and metadata (data about the data) components. The graphics are already stored in the CMS. Let’s say I send a document to the CMS and come back for it a couple of months later. During that time, some of the artwork has been changed. The CMS grabs the original content and metadata, rolls in the updated graphics, and hands me an ODF file. Oh cool, I didn’t have to update the graphics myself!

Another handy utility might be nightly publishing runs. Sometimes, I’m working on a manual that’s getting change requests and bug reports coming in fast & furious. Some of the manuals I deal with have a lot of bitmap graphics, and can take nearly an hour to generate a PDF. Remember, I’m lazy... I don’t want to sit at work an hour overtime just to watch the computer make a PDF. In my theoretical ODF-based system, I simply send in the stuff I worked on during the day, and the CMS builds a new document and emails it (with a summary of what changed) to all the reviewers. The reviewers get fresh hot documentation every morning; I get to go home, sit on the porch, and write haiku before it gets dark.

With the manual finished, I have to send it to the translators. Currently, this involves gathering all the various files together and archiving them (and sending missing pieces or assuring them that the extraneous files aren’t important). In my dream system, I tell the CMS to give me an ODF document of the book. Boom, all the pieces get wrapped together, nothing gets dropped, nothing extra gets added, and I send one file to the translators.

I’m willing to put some effort into making this a reality. After all, I want the computer to do the work for me.

More FrameMaker 7.2 Leakage

A post on the FrameUsers mailing list (thanks Thomas!) suggests doing a Google search on “FrameMaker new multiple undo” and then reading the cached page from Adobe UK (the first link when I tried it). Doing this turns up some more new features:

• multiple undo (one of those long-standing malfeatures I griped about yesterday)


• some support for XML Schema (probably conversion to EDD)


• support for native Photoshop (PSD) files

A sidebar had links for Solaris and Microsoft updates, suggesting that MacOS users are still left out. Figures.

Adobe Leaks FrameMaker 7.2 Info

In which I take a break from chronicling my personal life and talk about work stuff.

Over the Labor Day weekend, various pages on Adobe’s website mentioned the unreleased version 7.2 of FrameMaker, the preferred tool of the trade for most technical writers (who often affectionately call it “Frame”). Adobe (usually one to hold its cards close to the vest) has since revised the pages, although the old ones lived another day in Google’s caches before those too were updated.

But haste often leads to things getting skipped over, and that was the case with a migration guide white paper on Adobe Germany’s site. I grabbed an unrevised copy of the PDF Tuesday afternoon; the good people at Adobe.de have certainly gone home for the day but I expect the white paper to be sanitized first thing tomorrow morning (by about 2 a.m. EDT).

If you download too late, here’s what searching the PDF for “7.2” turned up in the way of new features:

• XSL processing at XML import and export (alongside existing read/write rules) — this is a feature I’ve wished for, but (see below) probably won’t get.


• Conversion tables, which add structure to unstructured files, can create a “first draft” EDD (a combination of DTD and style sheet).


• Conversion tables also support a “root element” to be applied to the converted document.

All this is structure-related, which doesn’t do you much good if you aren’t interested in moving to structured Frame. I’m sure that there will be the usual bug replacements (i.e. removing some known bugs and introducing new bugs) as well.

A group of vendors and trainers have been constantly flogging their “FrameMaker Chautauqua” conference on various mailing lists where FrameMaker is either the main or a common topic. The conference includes presentations by Adobe and will be held in early November, so I expect that Adobe will officially announce version 7.2 either at the conference or shortly before. If I’m right, it’s safe to assume that 7.2 is in beta testing right now.

FrameMaker has languished in a near-limbo pretty much since Adobe bought up Frame Technologies some years back. Frame has benefitted from minor updates from time to time, but long-standing bugs and malfeatures have persisted. That, and an abortive foray into porting the Unix version to Linux, have lead many to believe that Adobe is less than enthusiastic about supporting the program. The final straw for some of us was in January 2004, when Adobe dropped support for MacOS citing lack of sales (largely brought on by Adobe’s reluctance to modernize the MacOS version to run natively on MacOS X, leaving FrameMaker one of the last reasons to ever use the “Classic” environment).

Pretty much all summer, the “Chautauqua” people have been hyping Adobe’s presence at their upcoming conference, promising Frame users that they won’t be disappointed by what Adobe has to say about Frame’s life expectancy. Unfortunately, there’s no word on re-introducing MacOS support, preferably for MacOS X. That’s a show-stopper for me and many others: if the rest of the tool chain works well, why change the underlying platform if one tool is no longer supported?

Personally, even if Adobe repents of Windows-centricity, I’m not convinced that page-oriented WYSIWYG tools like Frame are the way forward for technical writing — in a world where our final output is more likely to be PDF and HTML than paper, it doesn’t make much sense to work on the electronic equivalent of a printed page. It makes more sense nowadays to work with markup, either directly (ooo, icky tags, say my less-technical brethren and sistren) or indirectly through an interface that provides formatting hints but no fixed margins or other page-centric details. LyX is a good example of the latter kind of program.

In the end, I expect little or no surprises come November. I’m certainly not going to ask my boss for $695 + hotel to attend a conference for a tool I’m currently planning to abandon, even if the conference is close enough to drive to.

A Boy and his computer

Current Music: BeatBlender
After a rather unpleasant episode Friday, The Boy and his aunt (whom we shall call “Big V” here on the blog) sort of patched things up between them. They have made a pact to help each other track their glucose levels (she's Type II, he's Type I), and today he had his act sufficiently together that he was pretty civil for a change (I've noticed he really gets whacked out when his glucose goes about 220 or so). So Friday, he was probably riding a serious sugar jag; he wrote this rambling letter about how much he hates us for trying to separate him & his girlfriend (we aren't trying, but would be overjoyed if it happened) and made a not-so-veiled threat to kill himself if he succeeded. That was enough to get me to call the local mental health agency and talk to a counselor there. We agreed that he needed to get in there, although there just wasn't any way to force him to go.

So today, he asked me to call him. Turns out he wanted to use the iMac that was still in his old bedroom to write papers and so forth. I didn't have any problem with that — when you need a computer you need a computer — so I tossed it and a smallish desk in the van and drove it down to Big V's place.

The interesting part was when I asked him what his paper was about. “Psychology,” he said. “I have to interview a psychologist.” Welllll, I was right there with a name and contact info on that one. On the way out, Big V stopped me and told me she was booting the girlfriend tomorrow because she was giving The Boy cigarettes. Perhaps our prayers are being answered!