Fair

and "balanced"
Everything here is my opinion. I do not speak for your employer.
January 2007
February 2007

2007-01-03 »

NITI in Retrospect: The Weaver 1.0 Manual

Ah, the irony. Just a day after I told sfllaw that I'm too lazy to put any pictures in this journal, I just spent about half an hour uploading some image scans (thanks, dad!).

Collection: Weaver Manual

My dad has what I believe to be the only traceable copy of the Weaver 1.0 manual currently in existence. Weaver, for those following the story, is the product-name-turned-codename of the early versions of Nitix.

Manuals That Don't Suck

Not so long ago I wrote about GourD, NITI's new system for generating quality documentation in a hopefully scalable way. I talked about the idea of an artistic integrator: someone who has been through the entire thing, from cover to cover, and made sure it's consistent and flows in a reasonable order.

Back then, that integrator was me. The content was co-written by dcoombs and myself in about a week, and then I went over it for stylistic consistency. The result? One of our earliest customers actually said that "it was so interesting that I ended up reading it cover to cover." So did the people making the (now defunct) Corel Netwinder: it earned me a contract to write the manual for their Netwinder OfficeServer. That contract, in turn, was the turning point in our tiny little startup: the payment on completion made us profitable for the very first time (including founders' salaries).

Other things of interest in the Weaver 1.0 manual: the pages were 5.5x8.5 inches (exactly half an 8.5x11 sheet, not coincidentally), which makes it look less scary than a full-sized 8.5x11 manual. The binding was cerlox, not "true" glue binding, because cerlox lies flat on a table like any reference manual should do. And there were less than 100 pages, because nobody wants to read a manual longer than 100 pages. (Of course, Weaver 1.0 had almost no features.)

Click the image to see a few page scans. My favourite is the Tunnel Vision diagram, from back when tunnelv was a hub-and-spoke system.

Blank Page Poetry

One of the great things about treating your manual as an art form is that you get to be an artist. When I get to be an artist, apparently I'm silly.

This particular art form was inspired by all the wasted space in manuals on "this page intentionally left blank" pages. Wasted space?! We're running a startup company on a shoestring budget, here, we can't be wasting space! So we didn't. Here's the progression of intentionally blank pages as you weave your way through the manual.

    This page intentionally left blank.
    ---
    This page intentionally not blank.
    ---
    Blankliness is next to godliness.
    ---
    There once was a page that was blank;
    Some people thought 'twas a prank.
        They read it out loud
        In front of a crowd
    And everyone thought that it stank. (--dcoombs)
    ---
    A blank page is not to be read;
    It should be skipped over briefly instead.
        If you follow this rule,
        You'll not be a fool,
    Nor confusedly scratching your head. (--me)
    ---
    We made this page blank not for spite;
    Nor even to give you a fright.
        They're publishing woes,
        For everyone knows
    That chapters must start on the right. (--me, or maybe dcoombs)
    ---
    A blank page causes despair;
    Something's supposed to be there.
        Did the printer break down?
        Did the ink jets leave town?
    We were hoping that no one would care. (--my mom)
    ---
    Please send useless filler to
    poetry@worldvisions.ca

(The poetry@ address is long dead. You can still send useless filler directly to me, if you want. And people do.)

And the moral of the story is, um, dcoombs writes better limericks than me.

Bonus: Deleted Netwinder Jokes

Incidentally, the aforementioned Netwinder guys changed almost nothing about the manual I wrote for them except for two jokes, which I will record here for reference since they're now too bankrupt to sue me.

First:

    (Context: I'm talking about using email aliases as mailing lists. We've added several names, including Al Gore, who back in 1999 had recently invented the internet, to a "smart-people@example.com" mailing list.) You can edit existing aliases in a similar way. For example, if you realize that Al Gore isn't smart after all, you can remove him from the smart-people alias by clicking the word Edit next to smart-people in the alias list. Edit the list of destinations, changing it to just einstein newton, and press OK.

What did they change? They replaced "Al Gore" in my example to "Mickey Mouse." Mickey Mouse is widely agreed not to be smart, but that's not the point. Apparently insulting what would turn out to be about 48% of the American voting districts (more than 50% of the popular vote) was not expected to be good for business. Wimps.

Second:

    (Context: Here, I'm explaining the concept of virtual web domains.) Consider what happens when you phone the cable company to request a service. You'll be sent to a voice mail system that asks you to push one button for sales, another button for service, another button to check your current billing information, and so on. Now, you and I both know that the cable company only employs one person to answer the phone calls during normal business hours (1 PM to 3 PM on alternate Tuesdays). But because you've gone through all the voice mail menus and your selections show up on his computer screen, the representative can answer the phone differently based on your requests. For example, he might choose to say "Hi, you've reached the sales department, please hold," or "Hi, you've reached the service department, please hold," as appropriate.

They removed this paragraph completely. Apparently insulting all the cable companies in the world at once was a bit much for them, since they were hoping to license their product through cable companies (sound familiar?). Wimps.

I'm CEO at Tailscale, where we make network problems disappear.

Why would you follow me on twitter? Use RSS.

apenwarr on gmail.com