Writing for Developers: Characters and Action

In the previous post in this series, we discussed nominalizations (verbs that have been transformed into abstract nouns), and how converting abstract nouns into concrete verbs can improve your prose. In this post, we’ll get a little deeper into why that is.

English sentence structure follows the form subject-verb-object (abbreviated SVO). In the sentence,

Amanda optimized the code.

“Amanda” is the subject, “optimized” is the verb, and “the code” is the object. Here we know that Amanda is the one doing the optimization, thanks to the sentence’s SVO structure and its context (it doesn’t make much sense for the code to be optimizing Amanda). If we pick a more ambiguous sentence,

Joanie murdered Chachi.

then the only thing we have to go on is SVO.

This brings us to characters and action. Even in highly abstract, technical prose, we tend to understand sentences in terms of characters (agents) who are performing actions. When a sentence hides the characters, or misdirects our attention onto the wrong characters, or obscures the main actions of the characters, the sentence becomes harder to read.

The good news is that all languages, including English, provide a basic structure that you can leverage to communicate these concepts. A sentence is clearer when the subject corresponds to the characters, and when the verb corresponds to the major actions of those characters.

Let’s start messing with our example sentence. To start with, Amanda doesn’t have to be the subject. We could write it this way,

The code was optimized by Amanda.

Now the code is the subject and Amanda is the object. Semantically, we know that Amanda is the “actor” or “agent”, and the code is the “goal” or “the thing receiving the action.”

“Amanda optimized the code,” is an example of an active sentence, where the subject is the character, and the object is the goal of the action. “The code was optimized by Amanda,” reverses this relationship: the goal is the subject and the character is the object. This is an example of a passive sentence, where the subject expresses the goal of the action.

As is often the case, the passive sentence is slightly worse than the active sentence. It’s a bit more wordy, and we have to do a bit more work to figure out who the character is. But we can make it a lot worse by using the powerful tool we learned about in the previous article, the nominalization, to mess with the action. Let’s turn the verb “optimize” into an abstract noun:

The optimization of the code was performed by Amanda.

Now that “optimization of the code” is the subject, the reader has to unpack the sentence even more carefully: they need to mentally discard the empty verb “performed,” and realize that the action is actually something else.

Alternatively, we can make our character Amanda disappear entirely, by removing the by-clause:

The code was optimized.

Perfect for avoiding giving credit, or diffusing blame!

Before closing, I want to be clear about two things. First, there are many ways to write bad prose that have nothing to do with passives. Second, passive sentences are a tool, and they exist in the language for a reason. In a subsequent post, I’ll provide some examples of using passive sentences for good, not evil. Until next time!

Writing for Developers: Nominalizations and You

Any engineer worth their salt knows that writing is a big part of the job. But for many of us, that can be a scary prospect. Some of us haven’t had a lot of formal training in writing, or English isn’t our native language — or both. We’re supposed to “write clearly,” but nobody ever explains how exactly to do that.

So I thought I would share one of my favorite low-level writing techniques. It’s widely applicable, and it’s doable as long as you are able to identify core parts of English (nouns, verbs, and adjectives). The technique is: find and eliminate nominalizations.

What is a Nominalization?

A nominalization is an abstract noun derived from a verb or adjective. For example:

  • initialize, the verb, becomes initialization, the abstract noun
  • minify, the verb, becomes minification, the abstract noun
  • elegant, the adjective, becomes elegance, the abstract noun

Side note: some nominalizations have the same form whether they’re an abstract noun or a verb. English is weird like that.

Aside from the occasional edge case (beyond the scope of this post), it’s usually an easy win to scan your draft for nominalizations and replace your abstract nouns with verbs and adjectives. Let’s see how this works in practice.

Example of Eliminating Nominalizations

Here’s an example of a very bad sentence (written by me, on purpose):

The Security Council’s proposal would provide for individual engineering team certification of the resilience of any new applications that were requested for exemption from core network security guidelines.

Here I have used all my dark powers to write an unclear, but still syntactically correct English sentence. Before continuing, please re-read this sentence as many times as you need to in order to understand what it’s saying.

How do we fix this mess? Let’s start by flagging the abstract nouns:

The Security Council’s proposal would provide for individual engineering team certification of the resilience of any new applications that were requested for exemption from core network security guidelines.

The equivalent concrete verbs and adjectives are:

  • proposal (noun) / propose (verb)
  • certification (noun) / certify (verb)
  • resilience (noun) / resilient (adjective)
  • exemption (noun) / exempt (verb)

Breaking into pieces and replacing the nominalizations looks like:

  • “The Security Council’s proposal” can become “The Security Council proposes”
  • “team certification of” can become “team certifies” or “team must certify”
  • “resilience of any new applications” can become “new applications are resilient”
  • “requested for exemption” can become “request [them/us/the council] to exempt” or even “ask […] to exempt”

Stitching the pieces back together:

The Security Council proposes that when individual engineering teams ask us to exempt new applications from core network security guidelines, the team must certify that the application is resilient.

This new sentence isn’t necessarily great, but we’ve at least managed to unscramble it. This is in spite of the fact that we haven’t radically shortened the sentence or done any deep surgery. The sentence still says what it said before, with mostly similar word choices. All we’ve done so far is convert four nominalizations (and if we’re being scrupulously honest, we’ve added a fifth verb, “ask”).

So why is the sentence easier to read? It’s because converting abstract nouns to verbs and adjectives has forced us to clarify who is doing what.

More generally, “clarifying who is doing what” is one of the more powerful tools you have available for improving your prose. This is often what readers actually mean when they complain, “This is unclear.” When a reader says this, a probable root cause is that the sentence hasn’t properly identified its characters and their actions. In the next post, I’ll dive into this in more detail.

HOWTO Create a Windows 8 Metro App with JS and YUI 3

Before reading further, readers should know:

  • I am a knucklehead.
  • I am not an engineer by any means.
  • I have no Windows development experience whatsoever. I do not know anything about the Windows developer stack.
  • My last Windows machine at home was a homebrew PC in 2002. That year, I switched to OS X. The last Windows machine I used at work was in early 2005.
  • The procedure below does things the stupid way, rather than the right or elegant way.

To sum up — me: knucklehead. Windows: alien territory.

Onward.

A Suboptimal Workflow for Metro App Development with YUI 3

  1. Download the Windows 8 Developer Preview. Install the ISO as a VM using VirtualBox, Fusion, or Parallels. FWIW, I used Parallels with 2 GB RAM on a 30 GB volume.

    Marvel at the fact that Windows installations take a lot less time today than they did on 2002-era hardware. Click through license agreements with enthusiasm. But don’t sign up for Live.

  2. Boot your brand new Windows 8 VM! Don’t let the fact that your virtual sound card is broken dampen your spirits.

    Stare at the brave new tablety world that is Windows 8. This doesn’t look like XP at all. You are… kind of intrigued, actually. Your Mom, however, is going to be super-pissed.

  3. Click the Visual Studio 11 square-thingy. Start a JS project and choose one of the built-in templates.

    It’s… a single-page web app! It uses a brand new JavaScript framework called Win-NIH.js. No, it’s actually called WinJS. It’s even documented. I’m sure it’s awesome.

  4. Delete all script and link references to WinJS and related CSS assets from the main default.html web page.

  5. Important: disable Visual Studio’s auto-id-mangling by going to Tools -> Options -> Text Editor -> HTML -> Miscellaneous and unchecking “Auto ID elements on paste in Source view”. (Thanks, Hardy Erlinger!) Otherwise, copying and pasting will cause Visual Studio 11 to stomp over all the IDs in the HTML, breaking your project. Yes, really.

    Now you’re going to need some code. So fire up Internet Explorer — might as well go all-in on this Microsoft stuff.

  6. Go to yuilibrary.com and view the TODO App Example, a toy single-page app that demonstrates how to use the YUI 3 App Framework. Scroll down to the bottom of the page, copy the complete TODO example, and paste it into default.html. Good artists copy, great artists steal.

  7. Now it’s time to load the YUI library itself, or at least the modules that power the YUI 3 TODO app. Go to the YUI 3 Dependency Configurator. Select the modules event-focus, json, model, model-list, and view in the configurator, copy the resulting combo-load URL, and paste that URL into a new IE tab. IE will offer to open or save the JavaScript file. Click Save.

  8. Return to the project in Visual Studio. Right-click the /js folder and add an existing file. Browse to the Downloads folder and add the combo.js file. When the file is imported to your project, feel free to rename it to yui-todo.js or something else meaningful.

  9. In default.html, add a script element with a src of /js/yui-todo.js above all other script elements.

  10. In the YUI().use() call, replace the list of module names with just '*'.

  11. From the Build menu, click Deploy. This builds your app and then side-loads it into your Windows environment, all in one step.

  12. Go back to the main Windows 8 tablety area. Scroll all the way to the right, and you will see your TODO app, with a generic black icon. Single-click to launch.

Congratulations! You’ve built, deployed, and run your first JS-style Metro app. It works exactly like the browser version. Except you can’t exit the app. Hahaha! You’re going to have to throw away your VM and start over.

Kidding. To quit the Metro app, hit the CMD button. To make changes, you’ll want to delete the deployed app from your environment before attempting to rebuild and redeploy the app again.

Elapsed time from launching Visual Studio (knowing nothing) to a deployed Metro app (still knowing nothing): a little under an hour. I actually wasted most of that time on other things:

  • Stumbling around an unfamiliar UI, figuring out how to navigate around etc.
  • Fooling around in Visual Studio — looking at the source files, building and deploying one of the default projects, building and deploying a static HTML page with one JS function all as a Hello World project, etc.
  • The big one, the ID-stompage problem. This eventually required doing a Debug build. I have no idea how to use the Visual Studio debugger, and it slows things down tremendously, but it does generate some JS console log output for you when you go back to run the app.

Observations

  • Despite running into a serious bug in Visual Studio 11, I was really impressed that the whole thing worked as advertised. You are not locked into WinJS at all. If it runs in IE 10, it should build as a Metro app. I dig it.
  • As You Know Bob, in the browser YUI 3 is meant to load a small seed file, and then asynchronously load module files from a server or CDN running a combo-loader. For Metro apps, we’re subverting this process by hand-crafting a physical rollup file of the modules we need and calling YUI().use('*'). Obviously, the way I actually created that rollup is a huge hack.
  • I haven’t actually tested the YUI 3 Loader in Metro — it would be neat if it worked — but the loader is probably not all that relevant for creating Metro apps anyway.
  • I don’t really know Visual Studio at all, so I don’t know how to develop iteratively there very well. Also, if you need to track down a runtime error, doing a Debug build is particularly painful. I’m sure Visual Studio experts know exactly how to do this stuff efficiently. See also: I am a knucklehead.

Anyway, my recommendation for the typical frontend engineer is to just stick with the development environment you like. Build and test your app in browsers, and basically just use Visual Studio as a build tool. I bet someone smarter than me knows how to automatically import code into Visual Studio and trigger a build headlessly. That would be nifty.

Postscript for Future Microsoft App Store Employees

If you have been wondering why you keep having to reject submissions of this weird “YUI 3 TODO app” — well, this post is probably why. My sincere apologies.

HOWTO Fix a ‘Mail has undone actions’ IMAP error

When using OS X Mail on Leopard with IMAP, it is possible to get Mail.app into a bad state with respect to the server. When this happens, Mail will start displaying an extremely-hard-to-dismiss dialog that resembles:

Mail has undone actions on some messages so that you can redo the actions while online.

Additional information: The IMAP command “UID COPY” (to Deleted Items) failed for the mailbox “Junk E-mail” with server error: Command Error. 10.

For the benefit of the entire Internets, here is the solution.

  1. Close Mail.app.

  2. Open a terminal and cd ~/Library/Mail/.

  3. In this directory is a subdirectory that is called something like IMAP-youremail@yourmailserver. (Or if you’re living dangerously and/or stupidly like me, Exchange-youremail@yourmailserver). cd into this directory.

  4. cd .OfflineCache/ and rm everything in this directory.

You’re welcome!

Decluttering for Geeks: Roleplaying Games

Welcome to Decluttering for Geeks. This is Part II of a four-part series:

  1. Part I: Computer Components
  2. Part II: RPGs
  3. Part III: Books
  4. Part IV: Media

A couple months ago, I was eating Korean BBQ with a bunch of software engineer friends from work. Someone asked, “So what are you guys up to this weekend”, and everyone chimed in with whatever geeky (or non-geeky) thing they had on their calendar. I said, “Oh, I’ve got you all beat. This Saturday night, I’m going to be kicking the tires of the new 4th edition Dungeons and Dragons rules with my buddies.” Lots of chuckles around the table, a few calls of “Nerd!”, etc. Mind you, being called “Nerd” by a bunch of software guys can sting a little, but nothing unexpected.

Except for one fellow who sat bolt upright. “Oh, oh! Can I play?!” The Geek Hierarchy works in mysterious ways.

Anyway, on to Roleplaying Games and Decluttering! Anyone think I can get through this post without making a lame “Bag of Holding” joke? Ladies and gentlemen, place your bets.

The Psychological

As with all decluttering problems, the core question is, “How much of this stuff do I really need?” Most RPG stuff falls into the following categories:

  • Core rulebooks. Keep, but only if you are currently playing. Be ruthless about this. If you don’t have a current gaming group, but you “want” to play, put your core rulebooks in a box. If after six months you haven’t played at least one game, declutter it all.
  • Core rulebooks from editions you are not playing. Declutter. Yes, I know these books can tug at the at heartstrings. Wow, a 1st edition Deities and Demigods — remember reading that in the third grade? Unfortunately, it’s worthless (unless it’s one of the rare, semi-illegal editions that include the Cthulhu/Melnibonean mythos). Unless you really like reading through Deities and Demigods on a daily basis so that you can memorize the hit points of the gods (SPOILER: Zeus has 400 HP), it’s best to let these books go. There’s someone else out there who can make use of them.
  • Supplementary and third-party rulebooks of all sorts. Declutter. If there’s a particular rule, campaign setting, or adventure seed that you’d like to use, Xerox it and get it out of the house.
  • Magazines. See “Supplementary rulebooks” above. Magazines often have wonderful tidbits and adventure seeds — clip & save the best, discard the rest.
  • Modules. Keep, if A) they match the game and edition you’re currently playing and B) your group hasn’t played it yet. Otherwise, declutter. Note that like rulebooks, the resale value for modules is often depressingly low. You might think that your classic S3-Expedition to the Barrier Peaks is worth a mint… come on, this one had vegepygmies! But nope, you can easily score one on eBay for just a few bucks.
  • Handmade adventures. Declutter.
  • Old character sheets. Seriously? Declutter. Both character sheets and adventures should be on the computer at this point.
  • Campaign material. If the material is still useful, transfer it to the computer and declutter. Otherwise, just declutter.
  • Dice. Keep, as long as 100% of your dice fit in a conveniently portable box.
  • Miniatures. A tricky one, because miniatures are useful and reusable, but they take up a lot of space. Try keeping miniatures only for the PCs; print out images for NPCs and bad guys on 1″ squares of cardstock, or use coins or other tokens. Lego men work great too. Note that I’m coming at this from the perspective of an RPGer — if you’re a wargamer, you probably need an entirely different decluttering article.

Note that as Michael Harrison suggests below, you can always declutter your physical products and then rebuy your favorites in electronic form at DriveThruRPG.com.

The Practical

Like computer components, most RPG material depreciates quickly, and perhaps for much the same reason. Unless the game is A) out of print and B) still very popular, used game material doesn’t hold its value very well.

  • Well, most used game material doesn’t hold its value very well, but it can’t hurt to look for the odd gem that’s worth separating out. The original Temple of Elemental Evil? It’s a classic, but pretty easy to get, not particularly valuable. Apparently there are a lot of copies still floating around, or not that many people playing 1st Edition, or both. But Monte Cook‘s excellent Return to the Temple of Elemental Evil? Worth at least thirty bucks, maybe fifty or sixty. So you never know. Sell these separately on Craigslist, eBay, etc.
  • For the bulk of your game material, the best option is to go to your Friendly Local Game Store (FLGS). Many FLGSes sell used games, and they might be willing to take your stuff off your hands for store credit or possibly even cash. In the Bay Area, I like Gator Games for this. Note that they’re not going to give you very much store credit or cash. Old gaming material takes up a lot of space on the shelf and might not sell. You’re not there to make a pile of cash, but to get your old game material into the hands of a fellow geek, someone who’s actually going to use and enjoy that material again.
  • If you can’t find a good FLGS, try a second hand bookstore.
  • Do not make the mistake of trying to sell the bulk of your stuff individually. You’ll get bogged down in trying to maximize your profit, your decluttering efforts will fall by the wayside, and at the end of the day, the extra dollars won’t add up to much.
  • Donate your material to a charity, library, or a local gaming club attached to a school. When it comes to helping create the next generation of gamer geeks, there’s no better authority than Tom Lehrer in The Old Dope Peddler:

He gives the kids free samples
because he knows full well
that today’s young innocent faces
will be tomorrow’s… clientele

RPG Decluttering. Because somewhere out there, there’s a 10×10′ room, waiting for someone new to kick down the door, kill the orc inside, and take his treasure.

Next time: Books, Comic and Otherwise!

Decluttering for Geeks: Computer Components

Welcome to Decluttering for Geeks. This is Part I of a four-part series:

  1. Part I: Computer Components
  2. Part II: RPGs
  3. Part III: Books
  4. Part IV: Media

So after glancing at the current crop of decluttering books, I think it’s safe to say that the subgenre of “decluttering for geeks” is underserved. Which is a bit disappointing, because we geeks have, shall we say, special needs when it comes to decluttering. Sure, some guy like Peter Walsh might give you some general guidelines to follow… but is he going to be able to intelligently advise you whether to keep your old copy of The Temple of Elemental Evil? What about Return to the Temple of Elemental Evil? Is this a trick question? Probably!

Typical decluttering books devote at least a chapter or two about why decluttering is a good thing. To save space, I’m going to assume that you’re already at least partly convinced. Here’s the thumbnail argument:

  • decluttering will save you time (you can find your stuff quickly)
  • decluttering will save you money (you can live in a smaller house, or avoid using external storage)
  • decluttering will save your sanity (you won’t be distracted by constant reminders of abandoned projects and rooms that need cleaning)

And here’s the thumbnail of the thumbnail argument. There but for the grace of God go we all.

Okay, so, computers. Most self-respecting geeks go through a phase of building their own computers. It’s fun to build exactly what you want, fun to compare and contrast different components with your fellow system builders, fun to put together a $500 box that outperforms the $2000 machine of the non-geek. You have powers beyond the ken of mortal men!

But like mathematics and women’s gymnastics, system building is a youngster’s game. Although the truly hardcore might stick with this hobby for decades, the typical geek burns out around their 30th birthday. All of a sudden, debugging overheating problems and scouring the internet for updated drivers becomes… less fun. You’ve reached the magical age where time begins to > money. Maybe it’s because you’re making more money, or maybe it’s because you feel the icy hand of death approaching. Either way, you sell out. You buy a Name Brand Computer, possibly a shiny silver one with a fruity logo. At first you feel guilty, dirty even. Then you get over it.

The end result is closets full of old, decaying systems, plus scads of individual components: Pentium II motherboards, PCI sound cards, and cables. Lots and lots of cables.

The Psychological

Before you can get rid of your computer stuff, you have to convince yourself to get rid of all your computer stuff. This is harder than it sounds.

So we’ll start with an anecdote. When I first started going through my cable collection, I pulled everything out of the desk drawers and tried to save only stuff I really needed. After about fifteen minutes of flailing around, I think I had decided to get rid of maybe two cables.

Sensing that things weren’t going so well, I called my girlfriend in, much like calling in an airstrike. The conversation proceeded as follows:

S: So, what’s this?

Me: Ah… I think that’s a USB A-to-B cable, still in its packaging. Hey, that’s kind of cool.

S: Have you needed this cable in the last two years?

Me: No.

S: Do you think you’ll need this cable in the next two years?

Me: Probably not.

S: Did you even know you had this cable?

Me: Nope.

S: What would you have done if you had decided you did need this cable?

Me: … gone to the store and bought one?

After that, it was pretty easy to narrow things down.

So why is it so hard for us to get rid of our old computer cruft? Here are some of the arguments we make to ourselves:

  • “This stuff is really valuable.” Wrong. Nothing depreciates faster than computer components. With the possible exception of certain cameras.
  • “I’ll save money by resurrecting this old box / building a useful box out of these components.” Wrong. That feeble eight-year-old box does not have enough CPU/watt to be worth powering on at all. Farm those tasks out to a machine that can do the same work for a fraction of the cost.
  • “I paid a lot of money for these components back in the day.” Irrelevant. What’s important is how much it’s worth right now (close to zero), versus how much money it’s costing you to store it (more than you think).
  • “This one is a classic, I’d just be sad to have to lose it.” Wrong. I have a friend, D, who has lovingly restored an original Amiga from his childhood. Maintaining the Amiga and being able to play some of its old games is a source of pride for D. But you are not D. Your “classic” machine is not being set up in a place of honor and shown off to fellow geeks. It’s sitting powered off and buried in a dusty closet. It needs to go.

The Practical

After figuring out what to get rid of, you’re faced with the the second problem: how to get rid of it. Electronics are tricky, because you can’t just toss them in the ordinary recycle bin. And it’s not always easy to sell them or give them away. When it comes to decluttering, I’m a strong believer in the “take time to find things a good home” philosophy… but computer components depreciate so quickly that it’s often hard to find anyone who wants them.

Some of your options include:

  • Donate to schools or charities: A reasonable choice, but only suitable for relatively new hardware that’s in good working order. You don’t want to saddle a school with an IBM Deskstar hard drive that’s mere days away from the Click of Death. Also, most schools and charities are savvy enough not to take old hardware anyway. They don’t have infinite time to tinker with dying machines.
  • Give it away: One geek’s trash is another geek’s treasure. You might know someone who still has the system builder bug. If you work at a large company, you might have a “free stuff” email list, and then there’s always Freecycle.
  • eBay or Craigslist: Getting a little cash for your stuff is always nice. But eBay is a bit of a trap, since once you start thinking about maximizing! my! return! on all this low-value hardware, you’ll end up holding onto it for a long time, possibly forever. The goal of this game is to get rid of the stuff. (It’s like playing Puerto Rico — at the end of the game, money is nearly irrelevant, it’s all about the victory points.)
  • Recycling: The EPA has a list of links for finding electronic waste recyclers and dropoff stations. If you’re lucky enough to live in the Bay Area, GreenCitizen has several locations and excellent rates, or you can drop your stuff off for free at WeirdStuff in Sunnyvale. They’ll go through your broken and crappy stuff, take what they want, and recycle the rest. Highly recommended. Just make sure you leave the loading dock immediately, and don’t make the rookie mistake of wandering through the WeirdStuff warehouse. There’s only one way to win at decluttering, and that’s not it.

Next time: Role-playing games!

Mac Tricks and Tips and Apps that are Real Good and Stuff

Dru recently won a shiny new Mac. Now he’s wondering about tips and tricks and what he should do with it. I was going to add my advice as a comment to his LJ, but then I realized, hey — this comment is getting so long, it’s totally turning into a free blog post! Ahem.

Dru complains about the menu at the top. I hear you man, it took me about two weeks to train myself to look there, and not at the window itself. Also, closing windows (often) does not close the app. Strange but true.

Tip #1: Yes, you can use a two-button mouse with a Mac. This very minute I am using the Microsoft Wireless Lasermouse 6000, with two buttons, two side buttons, and a clickable scroll wheel. Say what you will about Microsoft, they make some fine peripherals. And no, I haven’t been struck by lightning.

Tip #2: You can convert every file you open in a mac to PDF for free, via the Print menu.

Good mac resources: a bit hard to find, as most mac forums out there are too fanboyish. (Something’s wrong with your Mac? No, something’s wrong with you!)
The only forum I know of with any sense of perspective is Ars Technica’s Mac forum. There are a number of big-name Mac blogs out there but most of the ones I’ve tried subscribing to are vastly overrated. The only other Mac web resource I like is the Macrumors Buyers Guide, which gives you some idea of when the next hardware update is coming, based on historical data.

Software apps. For geeks, the three big ones would be MacPorts (UNIX package manager), XCode (Mac dev environment), and Quicksilver (app launcher plus so much more). Dru is already aware of these, so I’ll move on to my favorite software, almost all of which is Mac-only.

  • Angband: free rogue-like game, incredibly addictive. Not Mac-only, though.
  • Connoisseur: holds your recipes! How awesome is that! Isn’t that why every household was going to rush out and get a personal computer, back in 1980?
  • Delicious Library: holds your book collection. An attractive app, but not terribly useful. It is good if you loan out a lot of books, otherwise it has no real function other than to reduce your OCD.
  • Keychain: comes with the OS, holds your keys and passwords. Most people don’t even know it exists — I didn’t figure it out until a couple years into owning a Mac. I like it just fine, but since Dru is a security professional, there are a number of powerful third party apps.
  • Mail: The default Apple Mail has some drawbacks, but one big bonus is that it works with Spotlight, Apple’s search framework. DANGER WILL ROBINSON: Mail uses a proprietary format for email, so you might be locked in (compared to say Thunderbird which uses mbox). Actually, it’s a sort of bastardized Maildir, so it’s pretty straightforward to convert. Thanks, Sam Kingston!
  • NetNewsWire: excellent free RSS reader.
  • OmniFocus: a very powerful GTD app.
  • OmniGraffle Pro: for diagrams. Like Visio but in my opinion much nicer to use.
  • OmniOutliner Pro: an outlining program. There are a lot of good outliners available for the Mac, but this one is my personal favorite. Though I use it less now, because of OmniFocus.
  • Plaxo: Plaxo is not Mac-only. And a lot of people hate Plaxo because way back in the day they were pretty spammy. However, Plaxo syncs my address book and calendar between my work and home machine, which is just too danged useful to give up. I should note that, Plaxo has borked my calendar and addressbook twice in the past, but it’s been good for the last few months. To be perfectly honest, it’s a love/hate relationship.
  • SuperDuper: Great app for cloning and backups. Leopard now has Time Machine, which obviates some of the need for SuperDuper. But Time Machine can’t do everything SuperDuper can, like making a bootable clone.
  • Spaceward Ho!: excellent old-school space conquest game, with hilarious cowboy sound effects.
  • TextMate: a GUI text editor that happens to be elegant and yet highly customizable and UNIX friendly at the same time.
  • Transmit: a very good GUI FTP client.
  • TurboTax: well, this is available for Windows too, but in any case, it’s indispensable. See, for nearly a decade, I did my taxes all by hand, just like my father before me. But every year they got more complicated. I’m actually pretty good at elementary school math, but checking and double-checking all my tax forms was just getting tedious. Finally, I said to myself, “Man! It would really be great if someone would invent some kind of machine that was, like, really, really good at doing arithmetic and looking things up in tables. That would be just swell!” So. TurboTax. A good idea. And works great on the Mac.

How to Convert AuthorIT to DocBook

Because the public demanded it! This is really just an overview of the process, but it should give you a basic idea about what to watch out for.

  1. Convert your AuthorIT book to DITA.

    DITA (Darwin Information Typing Architecture) is one of AuthorIT’s built-in publishing formats. Publishing to DITA results in a folder containing your book’s image files, a collection of *.dita files, and a toc.ditamap file.

    Sadly, you must take this opportunity to wave your index markers a fond farewell. They are apparently too old and frail to survive this stage of the journey.

  2. Download the DITA Open Toolkit.

    The DITA Open Toolkit (DITA-OT) is a collection of Apache Ant scripts, XSL stylesheets, and other goodies that enable you to transform DITA into other formats, including DocBook. For those of you who don’t live in the Java world, Ant is basically make for Java. Newer versions of DITA-OT conveniently include a copy of Ant, so you don’t need to install it separately.

    To install DITA-OT, unzip the toolkit’s files into any directory and run the startcmd.sh script (or startcmd.bat script on Windows) to configure your CLASSPATH and other environment variables. If you forget to set your CLASSPATH, the toolkit will helpfully indicate this to you by bailing out mid-transformation and complaining that the Ant script is broken.

    Before you run any DocBook transformations, edit xsl/docbook/topic2db.xsl and comment out the template that contains “Related links”. The only thing this template does is riddle your DocBook with invalid itemizedlist elements.

    Do not waste time reading the toolkit’s documentation. The manual that ships with DITA-OT 1.3 actually applies to DITA-OT 1.2, so most of the examples are broken. As for grammar and clarity, let’s just say that the manual’s translation from the original Old Frisian leaves much to be desired.

  3. Transform the DITA document into DocBook.

    All the toolkit’s transformations involve running an Ant script:

    ant options targets

    To transform DITA to Docbook, run:

    ant -Dargs.input=path/toc.ditamap dita2docbook

    If the transform fails (and all your environment variables are set correctly), there might be errors lurking in your generated DITA source. This is AuthorIT’s way of telling you, “Don’t let the door hit you on the way out, jerk!”

    • If DITA-OT complains about a missing topic reference, there’s a good chance toc.ditamap is referencing a topic that doesn’t exist. Go back to the original AuthorIT doc and try to identify the missing topic. If all else fails, delete the reference from toc.ditamap and move on. Your readers already knew about the safety hazards of handling lithium deuteride, anyway.
    • If a topic contains a xref with a crazy relative path, this can really confuse DITA-OT. The good news is that the toolkit indicates the path that is causing the problem. The bad news is that AuthorIT dumps its DITA output in UTF-16, which is really annoying to grep through.
    • If you had any “Note” paragraph styles in your AuthorIT doc, these might disappear. Even more strangely, “Warning” paragraphs do make it through.
  4. Clean up the DocBook output with a script.

    Congratulations, your document is now DocBook! Well, more accurately, it’s “DocBook”. Just be happy your tables made it through, sort of.

    Fortunately, you can fix many issues pretty easily by running the document through a cleanup script. This script is particularly important if you’re converting multiple documents. The canonical language for the script is XSLT, but if you’d rather stick it to the W3C Man, Python or Perl would work fine too. Here’s what you’ll want to fix:

    • Remove all id attributes. These generated IDs are duplicated throughout the doc, and nothing points to them. Throw them away and start over.
    • Remove all remap attributes. In theory, these attributes contain useful information about the original DITA element, which in turn could help you design your post-processing script to provide better-quality DocBook markup. In practice… eh, not so much.
    • Remove all sectioninfo elements. They’re often invalid, and always contain nothing useful.
    • Remove empty type attributes. Not sure how those got there.
    • Remove empty para elements.
    • Change sidebar elements to section elements. Like the empty type attributes, these are another mystery guest.
    • Join programlisting elements. If you had any multi-line code samples, you might find that in the transformed DocBook, each line appears in its own programlisting. Join adjacent programlisting elements into a single programlisting (or screen, if appropriate).
    • (Optional) Change the article to a book, if appropriate. Add chapter elements as necessary.
    • (Optional) Try to improve the quality of the markup by changing emphasis role="bold" and literal elements to something more specific. For example, you define a list of commands that appear in your book and wrap each one in a command element. Creating explicit lists of commands, GUI buttons, and so on is tedious, but it’s still better to do these substitutions in the script.

    Finally, there’s the issue of broken IDs and links. Currently, every one of your AuthorIT hyperlinks is now a ulink that falls into one of these categories:

    • The ulink‘s url starts with “mailto:“. Convert these to email elements.
    • The ulink‘s url starts with “http://“, or “ftp://“, or “gopher://“. Leave these alone.
    • The ulink‘s url points to something like “D1228.xml“, a.k.a. nowhere. These are your former internal hyperlinks. They’re all broken.

    But don’t be discouraged, your script can actually “guess” at where many of these links should point. If a given internal ulink contains something like, “Configuring the MIRV Launch Sequence”, there’s an excellent chance that somewhere else in your document there’s a section with a title, “Configuring the MIRV Launch Sequence”! So all you have to do is:

    1. Convert the content of each ulink to a nicely-formatted ID. Replace whitespace with underscores, remove extraneous punctuation, and lower-casing everything.
    2. Convert the ulink to an xref, setting the linkend to the new ID.
    3. For each section element, apply the same ID-conversion algorithm to the section‘s title. Set this value as the section‘s id.

    A healthy fraction of your ids and linkends should now match up, fixing those broken links.

  5. Clean up the DocBook output manually.

    Oh, you’re not done yet! Here’s a non-exhaustive list of what’s left:

    • Fix the remaining invalid ids and broken links that your script didn’t catch.
    • Fix any other DocBook validity issues.
    • Add programlisting and screen elements where appropriate. Remove excess carriage returns as necessary.
    • Make your inline markup consistent. For example, all command-line tools should be consistently marked up as commands (assuming your organization chooses to use that element). You can partly script this, but mostly this is a manual job.
    • Remove any mysterious duplicate sections.
    • Rename your images from “898.png” to something more descriptive, such as “mirv_reentry_trajectory.png“. Embed the images in a figure with a proper title and id.
    • Add any missing front matter.
    • Rebuild your index by hand. By hand. Jesus H. Christ.

    Now put your feet up on the desk and pour yourself a well-deserved gin-and-tonic. If anyone asks you why you look so frazzled, do not under any circumstances tell the truth. Otherwise they’ll just respond with, “Well, why don’t you just move it all to the corporate wiki?” And there’s only one rational reaction to that. Don’t get me wrong, it’s not easy to inflict serious blunt force trauma using a 15″ Powerbook, but somehow, you’ll find a way.

The Market Value of OS 9

First things first. If you have an IBM GXP Deskstar hard drive:

  1. Stop reading this journal entry.
  2. Backup all your critical data right this minute.
  3. Run to your local computer equipment vendor and purchase a non-IBM, non-Seagate disk drive.
  4. Install your new hard drive and copy over your critical data, reinstalling your OS and applications as necessary.
  5. Take an axe to your IBM GXP Deskstar hard drive.
  6. Resume reading this journal entry.

So losing my hard drive after only a year and a half wasn’t as bad as you might think. Okay, I’ll admit I’m pretty annoyed with IBM for knowingly manufacturing defective hard drives. And it’s disheartening to find out that Apple chose to use those defective hard drives as their stock Quicksilver PowerMac drive. But I’m past that now, mostly because I had my critical files backed up. I was actually feeling pretty smug about that. Hah, silly people who lose data.

Until I discovered that I needed to use FrameMaker at home to edit some files that very day.[1] See, FrameMaker for the Macintosh is a “Classic” application, and unfortunately, my laptop didn’t have OS 9 installed. It used to have a Classic environment, but I had reinstalled Jaguar a while back and never bothered to re-install OS 9. Here’s what I learned that day:

  • Market value of OS 9, if you save your laptop’s OS 9 disk like a responsible person: $0.00.
  • Market value of OS 9, if you need to order a replacement OS 9 CD from Apple, to be delivered whenever UPS gets around to it: ~ $30.
  • Market value of OS 9, if you need OS 9 that day, and the clock is ticking: $86.52.

Tends to wipe the smug off one’s face, let me tell you.

1. As far as I can tell, Adobe FrameMaker 7 for Macintosh is essentially abandonware. One of the hazards of being a Mac user. No one bothers to write viruses for you, but no one bothers to write applications either.

2. Kidding, kidding. Of course people bother to write Macintosh viruses.