Programmers. Argh. (4.0, Premature Indigestion)

I suffered mightily from indigestion Tuesday and Wednesday evenings. I thought I was having a blood pressure spike, as the symptoms were about the same: chest pain/pressure, general feelings of uneasiness and shakiness. DoubleRed said her dad had a mini-heart attack with the same symptoms; we got out the BP machine Wednesday night and I was a tad high but the thing tends to read high anyway. Shortly after that, I began a long series of loud burps… about one a minute for an hour. Every time I’d let one loose, I felt a little better. By bedtime, I got to feeling fairly decent.

Thursday… let’s say whatever was causing the issue decided to move out. For Too Much Input, hover over this text. I still had a touch of whatever it was yesterday evening, but Mrs. Fetched attributed that to the Mexican food we had for lunch. Lord knows I’ve not exactly been eating right lately.

Skipping back a little… I got punted to a new department, which became official Monday. The new boss (not same as the old boss) came by Wednesday afternoon to get an idea of how I manage to get stuff done. I gave him a heads-up… as the new guy, he should expect a certain manager (the same one from Programmers 2.0, in fact) to start trying to poke his nose into the situation and dictating how I do my work.

I was right. I just didn’t expect it this week.

The opening shot came this morning, as part of an email chain concerning an update that we’d been handling through the week. Had I kept my mouth shut, I probably wouldn’t have had to worry about it, but I asked if we needed to update the translated User Guides as well. Another PITA engineer, who thinks his input is far more valuable than it actually is, wanted to know why we had French and Spanish for one product and Portuguese for another — the hobgoblin called Foolish Consistency rides that one hard — and the simple answer is that we sell one product through North America and the other in Brazil. “But we sell the other in Canada too,” said a manufacturing guy, and the seagull manager took wing with a comment to the new boss:

[You need] to make this multi-lingual translation routine and seemless [sic] for all our products.

I responded, “Routine and seamless? Good luck with that one.” We sell different products into different markets, and the markets often shift under our feet before I manage to finish the documentation. There is no “routine” when it comes to translation, simple as that. And seeing as it costs a fair amount of money for translation, there is no “seamless” unless we want to throw money away on translations we aren’t going to use… in this economy, that’s just stupid. I’ve already requested close to $10K for translations this year, and we’re not even through March yet. It also “seems” to me that someone who can’t even be bothered to turn on the spell checker in Notes should not be telling a writer how to do his job (“his” in this case is me).

I should have expected him to dig in… I have to give him this much, he won’t back down from a war of words even when he’s outmatched from the get-go. (Don’t start a flame war with a writer.) I suppose that’s a characteristic of empire-building; you can’t even admit to yourself that you’re on the wrong side on an argument. He whined about requirements (and there wasn’t even a Requirement Spec for this particular product), that the time and cost for translations seemed excessive (although he can’t really know since he’s not the one actually managing the process)… but the next part started (as Mrs. Fetched says) making my ass twitch:

We have impacted release dates in the past due to lack of translations. This is a problem area that needs to be fixed. […] delivery dates *MUST NOT* be gated by lack of documentation. This has to get fixed.

I wrote a nice little email that took him apart, paragraph by paragraph. In this particular case, we have had exactly one release date held up due to lack of translations (in 12 years), but he seems determined to hold that over my head at any opportunity… completely ignoring the myriad times development issues have held up releases. Perhaps if he was focused on hardware development instead of empire-building, they might meet more deadlines, but I didn’t say that. I went on to mention that documentation release dates keep getting pulled in, and the requirements for translations at the first build means I need to have completed and approved documentation (in English) 4–5 weeks earlier than that, so the translators have something to work from.

This took me to about 11:30 a.m. I wasn’t sure whether it was over the top (and the guideline is if you aren’t certain it’s not, it probably is), so I left the mail unsent and went to make a deposit at the credit union and grab some lunch (tried a random place along the way, a tad expensive but worth it). I figured a long hour, which included a motorcycle ride since I rode Little Zook to work, would give me some needed perspective. Alas, when I got back to work and looked over the email, I did some editing but didn’t see a need to tone it down at all. I sent it to my boss, who told me to not send it, let him handle it, and thanks for the info. No problem… I preferred to get some actual work done anyway.

With that not settled, but my participation thankfully out of the way, the discussion turned to yet another product. This is a “business services” product, so it doesn’t get end-user documentation, and people started questioning whether it should be done. As a necessity, I pointed out that we haven’t ever done translations for those kinds of documents, and asked whether we needed to start. One of the responses gave me a good laugh to end the day:

Maybe you'll have better luck getting an answer than I did.

And that’s the crux of the matter… I’m not going to request two grand or more for something I haven’t been told is needed. Maybe I should stop worrying and start stimulating the world economy.

But the indigestion, and its subsequent cause, are both gone now. There are days that the life of a chicken rancher looks like an improvement…

Eat to work, work to eat

I suggested stuffed bell peppers for supper tonight — I would have suggested it for yesterday, if we’d had some thawed ground beast. It was quite good, and she invited her parents up to help us eat it. Still, there was enough left over to stuff a microwave dish with a pepper, ear of corn, potatoes, and a slice of Mexican corn bread that Mrs. Fetched’s mom made (hot stuff! yum!). It won’t be any problem carrying it to work, since we’ll be getting my Civic first thing tomorrow.

Since the mom-in-law is going to the farmer’s market in the morning, I cleared the jalapeño bushes of the larger peppers, ending up with over two pounds of biiiig green chiles. Maybe someone will have cilantro and want to trade… I just can’t seem to grow cilantro.

The last of my “restricted” stock just got un-restricted. The HR department sent a memo around saying that they were going to use shares to withhold taxes, and “your net pay will not be affected.” Um… they forgot the Social Security part, which knocked a cool $600 off this paycheck, and I can ill afford to not have that money. I need to sell some of that stock, I guess… and since it’s lost about $2 in the last week, I’ll have to sell more than I needed to in the first place. At least I have the option (pun not intended). Maybe it will shoot back up tomorrow. Maybe pigs will… oh, never mind.

Programmers. Argh. (3.0, when “RTFM” is Just Too Much Effort)

I had to bang out an emergency project today — well, they’re all emergencies these days, but that’s beside the point. Knowing it had to be done today, I seriously considered working at home; I decided not to because The Boy is around and I didn’t want him interrupting me with spurious requests for money, car keys (missing driver’s license notwithstanding), a ride to somewhere, blah blah blah. There was also some camera work to be done, which usually involves my physical presence anyway.

Hindsight is 20/20.

Instead of The Boy, I had people popping into my cube all day and committing Documentus Interruptus — some of them were asking about the project I was trying to get done in spite of the interruptions. It was difficult at times to hold my tongue. Worst, though, was a programmer from down the aisle.

“Where in the manuals would I find Voice Quality Metrics?” “There’s a description in the Feature Guide, and instructions in the Troubleshooting Guide.”

“Where in the manuals would I find Loop Diagnostics?” (same answer)

At one point, I was about to get into The Zone — a rare state where I can out-produce just about anyone — when he popped in and barked my name a bit too loud, causing me to jump several inches.

“Sorry. Where would I find Loop Voltage Management?”

“Description in the Feature Guide. Instructions are either in Management or Provisioning, I can’t remember.”

“How could I find out?”

“Um… have you tried looking at the table of contents?”

I think he got the hint, because he didn’t come back the rest of the day.

The second most annoying visit was from the Vietnamese guy in Tech Support, who waved his hand alongside my head to get my attention (I have my iPod going most of the day, partly because the guy across from me is on the phone being Super Consumer Advocate half the time). Naturally, he wanted to know about the emergency project he’d just delayed.

I’d seriously considered, early on, grabbing a conference room and closing the door so nobody could find me. In retrospect, that’s exactly what I should have done.

I never did get to the camera work. Maybe tomorrow.

If you want to see the previous installment…

Good News, Bad News

Bad news first. Things at work have been absolutely crazy the last week or so. Trying to catch up, I brought a couple of projects home with me that are getting down to the wire. I managed to finish the first one this afternoon; trying to decide whether I want to do more than poke at the second one tonight.

The good news is that the documentation projects have rescued me from a weekend of chicken house duty. Given a choice between the two, I’ll take the work work any day.

We have snow flurries outside, and a good fire inside. Stay warm. Family Man, do some extra slacking for me tomorrow….

Post-Company Party Yawns

The company party was tonight, and was really nice this year. For one thing, it was on a weekend instead of after work so Mrs. Fetched came along — she doesn’t like doing the drive that I do five days a week. Heck, I don’t much like it myself, but someone has to deal with the cost of living. For another thing, they moved it from a restaurant near the office (last two years) to a club. Lots more room, better selection of food, and the bar served a great rum&coke. They cut back on the door prizes to offset the extra cost… but when you don’t win anyway, who cares?

But now I’m ready for bed. 'Night.

The Mobile Office

Current music: 1.fm Trance
It used to be that moving in the office was something you started hearing about long before it actually happened. There would be an alert that we would get moved in a few weeks, which would pass uneventfully and then we would forget about it. After a few months, the move alerts would come around again; sometimes it would again fade off. But eventually, the facilities people would bring around big stacks of flattened cardboard boxes and rolls of packaging tape on a Thursday, we would spend Friday marveling at how much stuff we had stuffed into 64 square feet, and spend the following Monday unpacking and pretending to try getting some work done.

That was so 2nd millennium.

Companies these days operate in Internet time, and moving is no exception. The feint-parry-thrust that once took weeks has now been compressed into a couple of hours. You hear the first rumor around 10 a.m. and you’re sitting in a new cube by 4. Fortunately, the facilities people do most of the moving for you nowadays. Virgil comes around with the cart, loads all the stuff you're not using at the moment (including the contents of the overheads and lateral), and sets it up in the new cube pretty much as it was. You’re left to clear the decorations off the walls, grab the Ethernet hub off the floor, and the phone and laptop off the desk. The only heavy lifting involves a 21" monitor. Spend an hour at the end of the day setting up the new place, get some work done, go home.

Even the phone is an instantaneous switch, thanks to the magic of VoIP. You yank the phone out of the Ethernet jack at the old place and plug it in at the new place. Done. No farting around with the PBX and maybe missing a call you didn’t want to take anyway.

The best part is that I can look out a window from my chair, for the first time in years (if you don’t count working at home). Just in time for winter to set in. This time of year, I need all the sunlight I can get.

New Toys

Wednesday, IT figured out what the last problem was setting up my MacBook Pro and brought it over. Sweeeeeet. I spent part of yesterday and today installing the other software I need and formatted my first documents on it this morning.

How much faster is it than my old work computer? I guesstimate about 15 times faster, and maybe 5 times faster than my iBook. I got a similar performance improvement switching from FrameMaker to groff. So the documentation suite that first got transformed out of Frame, four books totalling 750 pages, required half a day to create PDFs using Frame on the old 300MHz G3. Now it takes less than a minute. There is no longer any pain associated with accommodating last-minutes additions or changes — I can basically churn out a new version at a moment’s notice.

I told my boss, and he said, “You can get a lot more done now!” I said, “I love the smell of productivity in the morning. It smell like… slacking in the afternoon.” He thought that was pretty funny.

I was going to get a similar laptop for myself, but Mrs. Fetched confiscated the money I’d squirreled away for the purchase to pay for her cameras. And now she thinks she’s going to confiscate my Saturday for the chicken houses. I want to take my mountain bike to Nimblewill and ride around instead, but it occurs to me that I don’t have a car at the moment, thanks to The Boy. So I’m not sure what I’ll do tomorrow.

When You Rule the Tools

About a week ago, I complained about our tendency as tech writers to become slaves to our tools. Tonight I provide a counter-example — what becomes possible when you, the technical writer, is in charge of the tools.

At work, we’re building a box with built-in Wi-Fi capabilities and routing. Since that’s a fairly well-explored theme, we contracted a company in Taiwan to supply the Wi-Fi router. Like most routers for home networks, this one provides a web-based interface to configure the box, with links to context-sensitive help and a global glossary. As it turned out, the help that they furnished us was already owned (copyrighted) by another company. Since I work under the same department as the people driving this particular product, they brought me a working prototype and asked me to rewrite the help.

I’d seen an earlier prototype a few months back, so I already knew what was there. This time, though, I hit “View Source” in the browser — and was presented with a mishmash of HTML and <script> tags. Digging a little deeper, I realized that every single string in the web interface was being written by ECMAScript (the polite name for JavaScript hockkkk, ptui aka JavaSchit). The strings were stored as variables in files called language.js and langcont.js. The names explained the method to their madness: translating the interface requires changing only two files instead of 30.

Looking at the text itself, I was less than thrilled — we make stuff for cable companies; the help text talked about DSL and even ISDN, but not cable — and I had some better descriptions for other terms. The bolded term was run into the rest of the paragraph instead of broken out into a glossary-style list. I needed to add some cable-centric terms and remove the DSL- and ISDN-centric stuff.

So I fired up a text editor and got to work. It took all of five minutes for me to realize that I was going about it the wrong way. The string variables look like this:

h3='<b>Term</b> The definition…';

So if I wanted to add a new definition in between two existing ones, I’d have to either renumber everything following or create variables like h3_5 in between. Meanwhile, there was a corresponding <script> call in help.html:

<script language="javascript" type="text/javascript">dw(h3);</script>

To turn down the bloat a little, they had created dw as an alias for document.write. But the thing was, for every term I inserted or deleted in language.js, I’d have to make a corresponding fix in html.help. Since this is tedious, repetitive, kind of stuff — and I’m lazy — I decided to let the computer do the work for me. With a few global search and replace runs, I turned my text into HTML and then banged out a couple of scripts to transform it into the format needed by each file. It took an hour or so to get the scripts working, but I’d still be pounding on it if I had to do it by hand.

This is the kind of thing that you can’t do, or at least do easily, in Microsoft Weird or even FrameMaker. Even if it were possible, it wouldn’t be nearly as efficient. Sometimes, you even have to make tools to do a custom job on the spot. But when you rule the tools, the tools do the work for you so you can engage in some good old guilt-free slacking.

Professionalism, Rants, and Support

Techcommdood related a flare-up over Flare on techwr-l, a mailing list strictly dedicated to work-related communication by and for technical writers. He went on to say,

All facts removed, this was an inappropriate post. Why? Well, it offered little information and, well, it was a classic rant. You have to ask yourself, "What value did this add to the community?"

One word: none.

I don’t know about that. It pointed out some potentially serious problems with Flare, a fairly new help authoring tool (HAT) that’s trying to dethrone RoboHelp. MadCap (the company that produces Flare) stepped up and offered to work with the ranter to fix the problems, so maybe there’s a happy ending to come. Whatever: being a Mac user, neither MadCap nor Adobe (RoboHelp’s current owner) gives much of a rip about what I want or need.

Dood’s point was to decry the unprofessionalism of ranting on a public forum, whether directly or through an intermediary (as in this case) — of course, there’s Techcomm, a forum for tech writers that’s meant to be 95% rants and silly jokes, but that doesn’t really count. But there’s several kinds of unprofessionalism on display here, and they can all be seen in the ranter’s rhetorical question (caps lock removed): “Why should I pay $700 for a product and then spend my time doing workarounds to get it to do what it should do automatically?”

First, the ranter didn’t mention whether MadCap had tried to fix the problems before the rant, or if they were even aware of the problem. If you’re going to spend $700 for a piece of software, you should ask for help and expect to get it… and if you’re charging $700 for that software, you should a) make something that doesn’t break; and b) make sure your customers don’t get to the point of ranting about you in public. (The latter is often something that small companies like MadCap actually do better than larger ones like Adobe.)

The larger unprofessionalism is depending on some pretty $700 piece of software chrome to do your work for you. Face it, fellow tech writers, HTML (or even XML) is not rocket science. We complain about those icky tags, then we wonder why we get replaced by “technical writers” with a certificate education, at half the salary. Then there’s the whole issue of trusting your work to a monolithic database, which destroys everything when it gets corrupted (e.g. the late, unlamented ForeHelp), or any other software that doesn’t allow you to easily extract your work out of it (Word).

I’m not saying that we should be building help systems by hand — but we should certainly be willing to get involved at a much lower level. HTML-based help, after all, is simply a wrapper around a series of HTML (and graphic) files that provides (usually JavaScript-based) niceties like search and context. You provide table of contents and index files — and the content, of course — and that’s it. You don’t have to work directly with HTML — but you should be able to use what your authoring tool gives you to produce HTML, then be able to clean it up and prepare it for use with the help system. Yes, it takes a little time, but so does importing stuff into a dedicated HAT and fiddling with your content there.

Probably the most trouble-free help-building system I’ve seen to date is Mif2Go with FrameMaker to produce OmniHelp, an open-source help viewer. I’ve also used groff to produce HTML that works well with OmniHelp — everything can be modified to work the way you want it to, with no $700 “license fee” involved. Why are we not taking more advantage of set-ups like this?

It’s time to take control of our operating environments and to start living up to the title, technical writer. We’ve let the word become little more than a way to distinguish what we do from journalists and fiction writers for too long now, to our detriment.

The $3/gal threshold

This hit home yesterday... gas prices have stayed just under $3/gal here for a while now. At that price, if you use two gallons per day on your commute to work & back, working at home two days per week saves enough on gas to pay a $40 DSL bill each month.

So if you're trying to convince your spouse that you need broadband (or need to keep it), here’s your ammo.

Programmers. Argh (2.0)

Seagull: someone who makes a lot of noise, craps all over everything, then flies away.

It’s been a while since the last one of these, before I started Tales from FAR Manor in fact.

One of my recurring work projects is a four-volume set of software firmware documentation — one volume each for features, provisioning (i.e. installation and configuration), management, and troubleshooting. These are the “wonk” documents, as opposed to the consumer documents. I depend pretty heavily on the developers (i.e. programmers) to get me the information that I need to put into these documents, and their usual modus operandi is to wait until the last minute and drop a ton of changes on me.

On occasion, some of the things they want just, as Mrs. Fetched says, “get all over me.” In Programmers. Argh. 1.0, it was a request to add text to the manual, verbatim, that contained a howling grammatical error. This one is a bit more complicated, and started a couple of months ago with this request:

We *really* need section numbers in the documentation. I am asked *all the time* to explain how certain features work. I would like to just reference the correct guide and section number for the answer. With the way the document is structured, I have to go into the document and find a *string* to reference that can be searched on to find the information.

Now you have to remember that this is a programmer manager asking for section numbers. I haven’t used section numbers in customer documentation in nearly 20 years, and 98% of what I’ve done was for technically-oriented audiences. Not to mention that section numbers really wouldn’t solve his problem: the manual needs a better index, and he can use page numbers to refer them to the right place. I need to do a better job of indexing, I’ll be the first to admit, but the thing that bothers me is that they didn’t even think to include me in the discussion, or even forward any kind of post-mortem to me. I like getting comments about my work, so I can make it better (and if you, yes you, are wondering whether I want comments on my blog, the answer is yes).

Now it was my turn to make a mistake: I quickly wrote a response, saying pretty much what I just wrote, and Notes (once again) came up b0rk3n. I saved the reply in my Drafts folder and promptly forgot about it until it came up again.

Fast-forward to last week. Here come the comments, courtesy of the guy who pulled 1.0 on me, and guess what was at the top of the list? I started looking for the original request and found the response in Drafts. Cursing Notes and the IT department that forces us to use it, I updated the reply and sent it off. The bit-munchers were copying everything to my new boss, which only irked me more — not only do I suspect them of deliberately waiting to drop all their comments at the last minute so I’ll be the one late and officially holding up the release (giving them more time to fix their problems), they are trying to make me look bad to my boss. I sent him the general history of the project, including the stuff that has gone on before, and suggested he contact previous managers for confirmation.

He dug in, I dug in. You can’t out-flame a writer, and he probably knew that: all he had to do was stonewall until it was time for him to leave on two weeks vacation. But he may come back to find the company short one tech writer. One of my co-workers helped to diffuse the situation somewhat, arranging (and refereeing) a meeting between me and this guy’s manager (who kicked off this particular request). We compromised: I agreed to put chapter numbers and titles in the headers, especially since I’d planned to do it in the first place, and he agreed to start copying me on customer squawks that involved documentation. But I’m still pretty cheesed about the whole thing.

Time to find my resume and start emailing, I guess.

There's a sign...

... on the road ahead... and it says: “JOB BURNOUT - KEEP GOING.”

The question is: where do I turn off?

Work stuff

Some brief scenes of work lately....

I got moved to a different cube last week, after being told I wasn’t moving, which in turn came after I was told to get packing. This was the first time I’ve moved cubes where it wasn’t part of a group move: instead of grabbing boxes off a stack and told to pack up everything, a Facilities person did 90% of the job for me. He moved all the stuff that wasn’t on my desk (taking drawers or the entire piece of furniture), and all I had to do was clear the desk and set up my phones and computer at the new cube.

The new cube is an improvement, although it would have been hard to find a worse cube than the one I just left after several years: near a main traffic area, across from the training room (the trainer’s voice carries and he leaves the door open, not to mention the equipment noise), as far away from windows as possible. The new cube is near a window, and there’s a little chit-chat and equipment noise, but nothing my headphones can’t drown out.

One problem: the keyboard support was broken. I emailed the Facilities guy asking for a replacement, preferably with a mouse surface. So yesterday I came in to find a new platform on the floor and a Ryobi 18V drill in its case. When the assistant didn’t show up after an hour, I took drill in hand and did the five-minute transplant job myself. It’s a great stand; enough room to use it for lunch (after moving the keyboard).

Last night, I sat down and made a list of all the things I’d like to do given the time, or see happen in general. I might post it later, but none of the work-related items had anything to do with my current employment. Scary.

Grasping the nettle

Two projects blew up on me at work this week. That wouldn’t usually be a major problem — happens all the time — except that I got volunteered to run the games for Vacation Bible School at church this week. Then someone got the brilliant idea to start VBS at 6:30 instead of 7:00, which gave me no time to run home and get prepared... but now it’s out of my hands; I had to pass off the games to my (quite capable) assistant.

A while back, I mentioned wanting to move a desk into the bedroom, and expecting Mrs. Fetched to deprecate it as she usually does any idea of mine. But now it’s too hot to work on the porch (summers have attitude in the south, and the first day of summer had it in spades here), and everyone else was at VBS, so I just went ahead and did it. Then I ate some leftovers and got to work.

The family came in a bit after 9:00. Mrs. Fetched walked in, saw my setup, and said, “Good thing you cleaned that area up. That looks good there.” I was stunned but did a decent job of not showing it.

Just goes to show... Mrs. Fetched is completely predictable if you run an idea by her. But if you just do it, she’s completely random.

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.

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.

Peace & quiet

Current music: DI.fm Goa-Psy Trance
I came in from work, ran out to check over a presentation about a power line running past the church (and quite a few other places), and came back to Nobody Home. No jabbering TV, nobody Going To Die if I didn’t drop everything and fix her problem right away... sweeeet. I spent some time weeding down my inbox (now less than 100 messages from over 500 on Saturday) and catching up on some other folks’s blogs.

Digression, or maybe not: On the way home from work, I picked up a copy of Getting Things Done — it comes highly recommended in certain Mac geek circles — and made a short start of it. From the summary I saw at 43folders.com, it looks like a Master Plan for actually making Lotus Notes useful... which is a miracle that I’ve got to see for myself. I did manage, over the last couple of days, to whittle the couple-hundred messages out of my Notes inbox at work down to five (on Friday) and then to three (today). Next step is to wade through my project folders, clear out obsolete stuff, and move anything important into the Todo list.

An essential ingredient of Peace and Quiet is the lack of annoyance. Fortunately, there are few things harder to notice than something that is not annoying you. If that itch under my left shoulder blade isn’t itching, I don’t think about it. Upon finding the Monday morning meeting was cancelled (hooray!), I promptly forgot about it and did useful things all morning. I’m the kind of person who usually isn’t annoyed by low-level clutter, so I usually don’t notice it. (This is the source of some friction at FAR Manor, as Mrs. Fetched is annoyed by clutter... but often not enough to actually do something about it herself.) On the other hand, the TV is annoying, or at least distracting, so I tend to hike the iBook away from the living room and play music through a pair of earbuds.

There’s a drawback to forgetting about annoyances, though: when they come back, even when you know they’re coming back, their presence makes them twice as annoying... at least at first. I’m thinking about school buses — after the first week of summer vacation, I stop rejoicing in their absence and forget about them for the next two months (Two months? What happened to three months? This slow erosion of summer is ridiculous!).

Slumber calleth, so off to bed I go. Tuesdays and Thursdays are my work at home days, so I won’t be thinking about commuting tomorrow either.

Bonus babies, aka new toys

They passed out bonuses at work on Wednesday — a little earlier than I was prepared for, because I’d like a new MacBook but want to wait on the next hardware revision. So to assuage the technolust, I settled for getting an iPod and all the stuff I’ll need to go with it. Seeing my iBook is fairly old, it took nearly four hours to copy all my music and photos over a USB 1.1 port... just an incentive to get that newer laptop, I guess. We also picked up a 250GB hard drive for Mrs. Fetched’s video editing system — that G4 dualie has churned along for nearly four years now with no hardware upgrades, and it seems like 80GB drives aren’t as big as they used to be — and a set of noise-cancelling headphones.

I’d like to say one thing about the headphones: They. Are. FANTASTIC.

It seems to be an axiom that whatever the absolute worst cube in the office is, it will be assigned to me. The dwelling place I’ve been stuck with for the last couple of years is certainly a candidate if not the runaway winner — as far away from the windows as possible, along a main traffic route, and directly across from a training room with at least one of everything we make. Many of those products have fans, and they run all day. The only thing that drowns it out is the blare of the trainer, whose voice carries through most of that part of the building — he “can’t” shut the door because it would get too hot. The new headphones don’t do much for the chatter, but they easily knock out 80% of the fan noise emanating from the training room. Switching off the noise canceller produced a roar that I thought at first was blood rushing through my ears (like you might hear with a seriously good headset with no sound coming in), but was actually the training room.

I was impressed enough to risk official opprobrium by wearing them on the drive home, playing my iPod into the ’phones instead of through the FM transmitter thingie. Like wearing earplugs on the motorcycle, I think I hear better with the headphones: all the wind noise and road noise and climate control fan noise simply fades away; leaving only the hum of the engine, a little residual background stuff, and the music... which I can play at a much lower volume.

The only drawback is that they're the kind that hook over your ears, with the connecting band going around the back of your head. For whatever reason, they irritate my ears after a few hours.

I would pay some serious money for a “cone of silence” headset — something that would cut out both white noise and external chatter.

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.