VoIP... coming to an office near me

One of the IT folks came by my cube this afternoon, with a brand-new toy: a Cisco VoIP phone. Ain’t it cute?



Unfortunately, they don’t quite have them enabled yet. It came up, told me it was downloading a software update, then showed me this plaintive whine. The IT guy told me their plan was to roll the phones out to everyone, make sure they were doing their job, then cut everyone over. Presumably they’ll come to pick up the old Nortel PBX phones.


After looking at these pictures, all I can say is: my cellphone camera really sucks.

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.

December funk

Current music: Creation Steppin’ Radio
Sheesh. Not only is it December, it’s mid-December. Hey, at this rate I’ll wake up and it will be spring! (now that’s a happy thought)

Like most early winters, I wrestle with light deprivation and my disgust at the commercialist orgy that Christmas has become (if that O’reilly whackjob on Faux wanted to “save” Christmas, he should have started about 40 years ago). Unlike most early winters, this time it’s getting the better of me. The choir’s annual caroling & food basket delivery was this afternoon, and participating did more to boost my spirits than anything else has so far.

Another wrestling move I’m trying this year is been to throw myself into working over the technical writing chimeras called structure and metadata. Perhaps I didn’t dig deep enough, but most of the literature on metadata that I found in a Google search is geared more toward libraries and museums than technical writing.

The blob here is a mind-map of what I’ve come up with so far; I’m almost ready to start turning it into a paper (click the pic for something almost readable). The muddled state of the mind-map perhaps reflects the muddle in my own mind, but nothing I’ve run across so far has challenged my belief that most people involved are making things far more complex than need be. If I don’t write more about it on the blog, I’ll stash the paper somewhere and point to it.


But speaking of muddling, I’ll muddle through, like I always do. It’s nice that Christmas falls on a Sunday this year. Not being a member of a mega-church, we’re having a service on Christmas, although the pastor told me he’s thinking of just reading the story and letting it stand as such — not a bad idea, really. It will be nice to light that big white candle in the Advent wreath on the day it should be lit.

A funk isn’t much of a problem, in the grand scheme of things. A friend of The Boy’s spent last night at our house, and he and Lobster headed out about 10 this morning. About a mile down the road, he went off the road and literally flew over Lobster’s truck before rolling. Thank God he was wearing his seatbelt; the car is totaled but he has a split lip and needs a trip to the chiro-cracker. Lobster called 911 and waited until the first responders got there before leaving.

So later in the morning, Lobster calls from work in a near-panic. You see, he was supposed to hang around until the cops got there and give a statement; the cop who called him told him he needed to come down to the station to give his statement “and then we’ll decide if we should charge you with anything.” He was nearly freaked out, to the point where Mrs. Fetched agreed to go with him. He got off with a lecture, and a lot of teasing from everyone else, in the end.

Yes, there are things far worse than a simple funk. And the tinnitus has been mostly gone for two days, hallelujah!

XML for books: Simple is enough!

Many technical writers have been looking long and hard at working with XML, for a variety of reasons — ranging from a resume bullet-point to a genuine hope that it could improve productivity and help us better maintain our documentation. The problem is, vendors and consultants are the primary cheerleaders for XML solutions; they’re are all too ready to roll out six-figure systems to the few companies that have documentation departments with sufficient budgets and ignore all the rest of us. I’ve ranted in the Yahoo XML-doc mailing list about this topic, warning that XML is poised to sink into obscurity like its predecessor SGML, and for the same reasons. I truly believe that if XML is to gain widespread acceptance by technical writers, there needs to be a simple (cheap, easy to learn, no consultants required) XML-based system that can produce real documentation. Something no more complex than HTML, for example.

As it turns out, standard HTML may be all that’s needed. Printing a Book with CSS: Boom! describes how the authors created a published (to paper) book using HTML to mark up the text, and CSS (Cascading Style Sheets) to provide the formatting. The trick is to use a commercial CSS-based formatter that supports the proposed functionality in CSS3 (a future standard), which provides page layout necessities like headers and footers.

My hat is off to the authors. We now know that HTML/CSS is adequate for book publishing; knowing that it’s feasible is half the battle.

Happy Dance Time

Two (much larger) competitors of the company I work at find it too much of a struggle to compete, so they’re joining forces. Our stock got hammered on the news, but those things are temporary. We’ll continue doing what we do best while they’re sorting things out.

The real winners, though, are Scientific-Atlanta employees. I was a contractor there for 3½ years before moving to where I am now, and have stayed for eight years. Cisco’s modus operandi with new companies is to provide a thorough corporate culture enema, and no company I’ve been at — or heard of — needs one more than S-A.

S-A’s corporate culture still somehow reflects its roots as a McCarthy-era defense contractor. Employees are simply cogs in the machine, to be paid as little as possible and discarded at whim. I’m hunting for an email address for Cisco’s CEO (or at least HR department) and suggest they simply can everyone at S-A above the supervisor level, and a third to a half of the sup’s.

So on behalf of people I used to work with and still think of as friends, I do the happy dance. If it were a bit warmer, I’d dance naked around FAR Manor to celebrate.

Please Standby

Category: Work
Music: Groove Salad
I got included in an email chain at work late last week. To make a long story short, one of our customers was returning eMTAs (embedded MTA, a cable modem with phone lines built in) complaining that they could get dial tone but no Internet access. Our lab techs hooked them up to the test equipment, which reported No Fault Found. Upon further investigation, it turned out that somebody (whether a subscriber or an installation tech) was pressing the Standby button — which disconnects the Ethernet and USB ports from the cable network. The latest generation removed the Standby switch, since subscribers would also bump it unknowingly after installation, then complain that their service was out.

In some ways, we’ve made great advances and gone backwards simultaneously as far as user interface design goes. 40 or 50 years ago — let’s pretend personal computers were as available then as they are now for the sake of argument — a Standby switch would have been a big ol’ toggle switch on the front panel, clearly marked “STANDBY” up and “NORMAL” down. It would have been very easy to tell what mode the modem was in without trying to decipher a pattern of LEDs on the front panel. Product design these days is all about contours and smooth curves — a practical, easily visible toggle switch pokes out and just doesn’t fit today’s style.

Whatever happened to “form follows function”?

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.

Something you don't see everyday

I was getting my 3 p.m. joe to see me through the rest of the afternoon, and managed to get a whole cup for a change. As I was starting the next pot, the president of our division came in, said hello, then stooped down & picked up a couple of pieces of trash & dumped them in the wastebasket.

I guess that represents why I’ve stayed there for 7 years.

My ad hoc home office

I thought I’d start the day by describing my work-at-home setup before I get to work.

Last week, I said I work out on the screened-in porch/Florida room with the cats. I set at the windows, looking out over a very rough back yard that needs some serious log removal and weed-eating. The woods takes over about thirty feet away, so it’s a fairly narrow strip of yard I’m talking about.

I sit at an 80s-vintage typing desk, a steel frame with a pretty good composite veneer over who-knows-what for a working surface. I use two phone books to raise the iBook screen up to (almost) eye level... I suppose I ought to get one or two more to get it really right. The Boy’s old iMac “donated” its Apple Pro Keyboard & my MacAlly wheelie mouse (he likes it better than the Pro Mouse and I don’t use it that often) for the day.

The Force is strong with the litter box this morning. Daughter Dearest is supposed to scoop it at least every other day, and we’re lucky if she gets to it twice a week.

Time to start working, after I grab a cup of coffee... and a couple more phone books....

Working at home

Current music: Moody Blues - Say It With Love
I’ve sort-of fallen into a routine where I work at home on Tuesdays. Today it worked out even better than usual: Planetary Governor Bok-Bok asked school districts to take a couple of snow days Monday & Tuesday to cushion any Rita-related fuel shortages, so I didn't have to worry about getting the kids up and taking them to school. If that weren't good enough, I turned off the alarm so I could get a reasonable amount of sleep for a change.

Time to get some work done....

Yuck

I didn't realize how dirty my keyboard wrist rest was at the office until I dripped a little water on it and tried to rub it off. I had to get some soap on a paper towel to clean it off.

The stuff I have to document...

One of the products I write about at work has a command-line interface (CLI) used for debugging and troubleshooting. Customers got wind of it, requested documentation, and that’s usually where I get involved.

One particular (or should I say peculiar) troubleshooting command is “ti_ts” — which starts a troubleshooting routine on some TI chips in the box. I tried to get them to change the name, to no avail. So on this development cycle, they added a “codesperms” command (which translates to “active codes per minislot’). I have a pretty good idea what the next oddly-named command will be, but don’t want to give them ideas just in case one of them stumbles across this blog....

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.

Meet the new boss

Current Music: Creation Steppin' Radio
With all the other stuff going on around FAR Manor, I haven't really thought much about impending changes at work. I don't plan to go into deep detail about the workplace, partly because they haven't created a blogging policy. I'll have to talk a bit about the industry, though, for you to make any sense of the following. It's the supply-side of the cable (CATV) business; the company I work for makes cable modems, eMTAs (cable modems with telephone lines built in), and CMTSs (what the cable modems and eMTAs talk to at the other end of the cable). I've been writing the manuals for all but one of the products.

There's a lot of noise from analyst-types about the "triple play" in the cable industry -- that is, data (cable modems), telephony (eMTAs), and digital TV. Lately, I've been devoted full time to the latter. We're building a box that can take a bunch of digital video streams, moosh them around in pre-determined ways, and send them down the cable to your home theater or whatever.

Lately, we've been selling so many eMTAs that the management felt it necessary to divide the company along product lines -- eMTAs on this side, all the headend (cable company) stuff on the other. Just as my former boss hired a contractor to take the eMTA load off me, I got moved to the eMTA side.

I'm not complaining (for a change) -- it looks like I'm going to have an honest-to-God budget and the freedom to roll out web and video editions of documentation. I've been griping for about 7 years that we need to put our documentation online; looks like it might finally happen.