Ted, Ted, Ted

This is for Laura.

This is what we’re up against. Perfectly intelligent people can’t tell a white paper from a user guide.

before getting too excited. I don’t think they really have these cool floating cities yet.

I usually don’t go in for April Fool’s kind of stuff, but this is moderately funny, in a mildly geeky way.

Here’s a sane and fair-minded account of why the people who write our entertainment (without whom, of course, there would be no entertainment) started withholding their labor power this week. (Note for comics fans, such as Laura: the speaker, Brian Vaughan, did some of the writing on Runaways, our current favorite Marvel series.)

This fight has nothing to do with software writers like me, as far as I can tell, but if I see a picket line around here I’ll enthusiastically not cross it.

My friend Jeff, a CollabNet engineer and an astronomer, got up damn early the other morning and made these spectacular shots of the lunar eclipse.

Way cool. Obviously the biggest use of cabs is to get from the airport to the financial district and back. In San Francisco, that means to the upper right quadrant of the city map.

This and this, taken together, are about the coolest thing I have seen on the Web in months.

Writing is not a team activity. Editing is a team activity. Writing never works collectively, because it depends on a large number of threads being held simultaneously in a person’s short-term memory. That’s not something you can share. It’s a waste of time to try. Of course, people try all the time. We can see the results in bad corporate documents, legal boilerplate and technical drivel, and in the endless meetings held to hammer out that bad work.

Often someone says something in a meeting that captures a thought perfectly. It may even seem elegant, like something that everyone knows but that hasn’t been expressed so well until now. Someone will say, “Get that down.” Later, at editing time, it may turn out to make no sense at all. The context has changed, of course: what’s said in a meeting grows out of the experiences of everyone there, complete with unspoken assumptions, agreements and compromises. Text has no context at all. It appears out of nowhere, bearing all of its antecedents within itself. It has no hope of matching the immediacy of a spoken conversation.

Writing has a tense, complicated relationship with speech. Good writing gives the illusion of resembling speech, or being derived from speech. But writing that is transcribed from speech is generally bad writing. It does not feel like real speech. Some writing does feel like real speech; that writing can seem stilted when you read it out loud. The speech writing evokes is imaginary speech, speech that takes place in your mind’s ear.

Don’t write to cover your ass. It won’t work, and if you write well you won’t need it. Writing is not a contract. Diligently including every word that every stakeholder wants in the document is not writing but listing, note-taking, at best. Writing that aims to protect the writer from liability is not good writing, even if it is necessary sometimes. Preserving the ability to say, “Yes, we mentioned that, look right here” is not one of the goals of good writing.

Many technical people have been taught the virtue of brevity. They have been taught too well. Brevity is not any greater a virtue than punctuation. It is necessary, but not sufficient, and much less important than clarity.

Writing is an exercise in empathy. We test our writing by forgetting our own hard-won knowledge, positions and interests and reading our work from the perspective of the stranger. A turn of phrase that’s familiar to us may be baffling to someone who wasn’t in the room when that phrasing emerged. We can only know how baffling if we can suspend the self for a moment and read like someone who has no idea what is going on here. Good writers are able to suspend the self for sustained periods — to be both the stranger and the insider in turn.

I met the software architect for this cool Web 2.0 company at a staff party for one of the schools Mary works at. I’m thinking this could be a very useful tool for settling some of the burning questions that keep me awake nights, such as:

Here’s the web site for Starr King school that I put together using Wordpress last month. It’s going public this weekend at the school district enrollment fair. It came to a surprisingly small effort, compared with what it used to take to make a decent-looking web site. Wordpress takes care of a whole lot of the hard work for you, and Dreamhost (which I’m also using for this humble site) does some pretty fine hosting, especially their one-click install script, which puts up some fairly daunting applications (like Wordpress, Subversion, PHP) almost automatically.

I’m getting better at catching onto internet hipster buzzwords. At this rate, by 2008 I’ll notice one while it’s actually still in use. Going Bedouin appears to be a term of art for freeloading work space at cafes with free wireless, the way I do most of the week, and look, I’m only about nine months late catching on.

So I’ve been thinking. CollabNet (where I work) is all about tools for distributed development. (Mostly for software, but there are customers in biotech and manufacturing too.) Its main product includes a database component called Project Tracker (PT). The essential concept behind PT is the artifact, which is a generic work item that the user can configure to represent any measurable part of a project, such as an action item, requirement, trouble ticket, test plan, use case, or whatever. The idea is that you can build your own project tracking system out of artifacts that you design to match your very specific needs, while PT handles the back end for you — stuff like change tracking, reporting, and so on. We also provide some basic pre-designed artifacts out of the box, which many customers use until their needs get complex enough to require their own custom artifacts.

What I’m thinking is, what if there were an artifact that represented a DITA topic? This artifact would contain the actual content of the topic, plus the reviewing trail, plus the metadata that would enable you to assemble topics into outputs by running a query. A writer wouldn’t have to know any DITA markup to play in this game — they would just have to fill in fields, such as Shortdesc, Context, Step 1, Step 2, etc., which would be converted to DITA markup using the XML export functionality that PT has in spades. I think there is some precedent for a web-form-based model of topic drafting, although I don’t have any experience with it. This new XDocs thing, for example.
I say “just,” but of course I don’t mean that; there’s still a lot of skill involved, but its exercise is moved back from the text creation and tagging phase to the conceptual phase. Writers could spend most of their time and brainpower designing the document and defining the topics required. Once that’s done, the actual drafting might seem like an afterthought.

I’m putting this link here just to remind myself to look at some of these webinars.

I’m in India for the second half of October, working with my team of intrepid tech writers. The Divali holiday is coming up, which in scale and importance is kind of like Christmas and Thanksgiving put together, and it seems that people start preparing for it pretty early, because the traffic this week hasn’t been nearly as mad as it was when I was here last March. But it’s still pretty scary. I went for a stroll the other night with my colleague Jeff and we ended up just walking around the block our hotel was on, because we were too prudent to cross a main road.

Here’s the view from the hotel we stayed at first. (We only lasted two nights there due to a kind of musty odor that pervaded the place. But it was pretty nice other than that.) Chennai is a graceful city full of palm trees and shaded verandas. Fruit trees are everywhere, although you don’t see any fruit growing on them because hungry people pick it all. Some days the smog reminds you of Mexico City, but when the air is clear it’s very beautiful here.

I’ve been suspecting for years that I’m less and less a separate physical being, more and more a node of the Internet. What’s cool about this is that now you can’t even talk about the possibility of netlessness outside of the network.

Trying to decide what to make of this. Offshoring has been on my mind as I’ve been getting ready to spend the second half of October in India working with my tiny team of tech writers. I’ve been pretty clear on where I belong in this whole picture: I don’t trust corporations to manage globalization, I don’t think the economic or social effects are nearly as pretty on either side as the Friedmanite hacks propose, and I don’t think cheap and docile labor power is a very good trade for quality and productivity. On the other hand: I don’t think I can make a living without participating in the software industry, and that means having some role in an offshoring relationship no matter what company I work for. I’ve tried to do it ethically, making sure everyone my own work touches comes off the better for it and practicing as much cultural relativism as I can figure out how. And let me not deny I’ve had a lot of fun with it — for all its hassles, an India trip twice a year is a eal privilege.

Here’s something I’ve been working on as a support for training my documentation team to convert to XML, which is a bit more fun than it sounds like but requires some fairly fundamental rethinking of what a writer does. There is a labored and over-extended analogy with bees, but I think I might keep that in.
————————

To supply user documentation for a diverse, overlapping set of products, you have to maintain your information in tight, clearly delineated modules that you can mix and match wherever they are needed. To do this, you must discard the old book-based model that has defined most online documentation until recently, and make the transition to an agile database model.

What’s wrong with the old way?

Online documentation started out as an effort to duplicate the experience of reading a book, which was the main way people were used to getting information before computers became widespread. You can see the influence of many generations of book-reading in the language we use to talk about online experience: pages, scrolling, sections and headings, libraries, and so on. The book model was successful because its structure supported the way people actually interacted with things and events in the “real world,” as they called it (or “offline,” as they didn’t call it).

The problem is, online experience is very different from “real life.” Events are much more fragmented: you do one thing here, jump somewhere else to read something, come back for a moment, reboot, pull in some snippet of data from over there. Online experience doesn’t feel like the rhythmic, sequential narrative structure that we value in the books and manuals that we read on paper.

The supplies of information that we rely on to help us get through this madness don’t help us very much if they insist on portraying a world in which one thing follows another and everything develops according to an authoritative, reliable timeline. We need information to be available for just the activity we are on, at just the time we need it, in just the amount and at just the level that makes sense right then.

That’s the consuming side. As suppliers of information for people using computers, we’re called on to provide information that supports the way our readers actually behave online. If our information is locked up in large, unique, cohesive batches of prose, we can expect to spend most of our time searching and editing and managing those batches, leading to more and more duplication, inefficiency and human error.

What’s good about the new way?

Real computer users can be compared to a bee in a garden. They hover around, briefly select a landing place and move on when they have what they came for, then do it again. Their effectiveness is determined by how much they can get out of each flower they visit. The more specific information they can derice from each of those flowers (What is this color exactly? How did I get here? How much pollen can I get from this variety?), the better their overall honey-making day.

We can’t predict which flower a bee will visit next. We can predict, though, that it won’t follow a schedule of stops at particular ones. That’s what a manual is, or a guide: a schedule of stops at particular screens, pages or resources. We would never offer a bee a schedule for its pollen-gathering chores: that would be silly.

What we might do instead is develop a collection of discrete bits of information about all the different things the bee has to get done. Some of those bits only make sense when a bee is visiting a particular species of flower. Others are more generally useful, like navigational hints.

It would take some work. We would have to watch the bees carefully, to develop a model of where they go and how they do things. We would have to keep close track of our bits of information, so as not to describe the same thing twice, or leave out something important.

Then, if we could figure out a way to attach to each flower a unique set of those information bits, including everything the bee needs to know right then and there and nothing it doesn’t need to know, we could really make that bee a champion pollen-collector.

If our information bits were sufficiently standardized so we could mix and match them freely, we could put together such a set of information on the spur of the moment, even for a flower that we didn’t even know about.

If, on top of that, we could make that information pop up in front of the bee, with the bee barely even realizing it had triggered it, we would be revolutionizing the work lives of bees. We’d be on the cover of National Geographic.

At least two nights a week I have to get back on the clock after the kids are in bed, for phone meetings with the India branch of the company I work for. Most meetings are in our evening hours, their morning. My own team meets at 10 pm Tuesdays (10:30 a.m. Wednesday, India time) and there are other meetings irregularly throughout the week. You get used to it. One of the odder things I’ve noticed is that people on our end will sign off by saying, “Good night. Have a good day.” The first part refers to our time zone, the second to theirs.

Disambiguate.

Got to be kidding. First person on my team to use this word gets 10 pushups.