What I Would Like in a Technical Documentation Editor

Motivation: I've begun writing an introduction to the Eiffel programming language. Being very constrained in how much time I can dedicate to this, I'm frustrated by the tedium of developing the text and the examples in parallel, and trying to keep the two in sync. It would be great if I could develop the code examples outside of the document and then integrate them into it seamlessly, or if I could develop the code in the document and then have the examples automatically become test programs, or even better, go both ways.

It should support the evolution of the code as I write the book, and the evolution of the examples as the code progresses through the book.

In some ways, this like literate programming, but goes deeper, since I want to iterate over the examples and refine them.

1. Ease of use -- of course
2. The ability to extract entire programs from the document and automatically compile and test them.
3. Cohesion of code fragments. When a fragment is repeated in different sections, every place that fragment is referenced is properly updated. In other words, rather than the code itself, what's in the document is a reference to the code that gets expanded appropriate for display purposes?
4. Appropriate styling of code. Reserved words should be one format, regular code another, comments italicized, etc.
5. Wiki-like reference support. In addition to styling the text, I'd like the reserved words to become links to documentation that explains them, or explains the programming construct(s) that use them, or both.
6. The Wiki-like references can go deeper. When the text makes a reference to a concept like "Boolean expression" then the text should automatically become a reference to the explanation or sidebar about boolean expressions.

In other words, I would like an editing tool that can read my mind, is extremely efficient for generating intertwined code and documents, that makes optimum use of the hypertext capabilities of electronic publishing, and can then coerce documents and code into a format that's completely acceptable for printing.

The tool (or suite of tools) should automatically verify the integrity of the document in parts and as a whole.

Welcome to China!

We arrived at Dalian (a large harbor city close to Beijing) on a cruise ship in late one evening in October, 2005. Berthed next to us is a barge unloading scrap metal. A huge claw descends into its hold, pulls out a load and the drops it on a large pile with a horrendous clatter.

Across the dock from us stands a squalid, three story building in desperate need of repair. Weeds sprout from cracks on the trash-strewn roof. Raw brick and mortar stand exposed where the plaster has fallen away. Rust stains weep down the walls.

Below us handful of Chinese soldiers patrol the dock the gangway. They stand alertly despite the late hour, the cold, and the dim lighting.

Somone familiar with mainland China says that our captain must not have properly bribed the inspectors with food, wine and red bags. But who can blame him? To get into Japan or Korea, only three customs inspectors came aboard. Since China has many more people, they apparently also have many more inspectors; they sent thirty. It was a little humorous watching them tour the ship. They looked more like tourists than the passengers. So they had to eat at the buffet line, and didn't get any free hootch, and to show their displeasure we had to dock at this garden spot instead of the much nicer berth at another pier. Maybe the captain would have hospitably received a small delegation; hosting a busload would be off-putting.

As I watched the guards mill about and the barge being unloaded, a shiny white car raced down the dock and close to the gangway. "Ooh, someone important has arrived."

No one got out for a while, then the driver emerged. He was here to pick up someone important, not drop them off. He paced the length of the ship. He didn't see the passengers watching him from above (cruise ships are pretty tall). As he drew closer to the ship, he boosted up on tippy toe and tried to peek in through the lower portholes. "What's the pervert looking at?" I asked, sotto voce. My fellow passengers laughed. The driver noticed us and wandered away from our ship.

Another passenger asked why they needed soldiers on the dock. "They are concerned that we may try to sneak off the ship and illegally migrate to this Worker's Paradise."

Before disembarking I had to fill out a health questionnare (have you ever been treated for psychosis? Have you ever been diagnosed with a venereal disease?), and when I handed the form over to those kind and caring Chinese officials, they demonstrated their concern for my health by taking my temperature.

To take our temperatures, they used a little thermal scanner waved over the right thumb. I'm left handed, and was corrected when I offered the wrong thumb. Maybe these scanners are more accurate with right thumbs than left? I wondered what would happen if I clutched a bit of ice in my hand before getting scanned. "This fellow can't go ashore. He's dead!"

Of course, once you get past the officials and the ugly dockside architecture, the city is quite nice. And I have to say, all the passengers I saw and talked to took the whole thing very much in stride. It's almost as if they felt sorry for these poor benighted Chinese officials, stooping to such silly behavior.

What I Did Today

Today I have developed a new branch of mathematics related to set theory. I call it infinite transgressions.

The California Real Estate Market

I originally wrote this post in 2006. We've hit the major correction I mentioned in the article, but I think many of these issues are still relevant, given a market that is defined by high costs and low liquidity.

When we first moved to the Bay Area, we searched for a new home for several years. The real estate market had a single, unwritten rule:

Rule #1: Screw the Buyer

I've seen what must be hundreds of houses and I've talked with dozens of real estate agents. I finally found one broker who was willing to work with us as an agent's buyer for a flat fee, on the premise that my wife and I would do all the legwork. He'd only be involved in writing offer letters and any final contract negotiation. This was perhaps one of the smartest moves we could have made.

Here's how buyers get screwed in this market.

1) Your agent doesn't really represent your best interests. Buyers' agents are paid a percentage of the gross. They have a strong incentive to get the deal done as quickly as possible, not to get you the lowest possible price on a house. We've had agents pressure us to make offers way above asking "to be sure we got in while we could". In one case we backed off from a deal where the agent tried to strong-arm us into increasing a good offer by another $50,000. Angry, we walked away. The house eventually sold for $50,000 less than what we'd originally offered.

2) Agents on both sides can withhold and distort price information. A free market is based on the free exchange of information, or at least I thought so. If real estate is a free market, then as a potential buyer shouldn't I be allowed to know what other bids have been placed on a house, and the amount of those bids? Apparently not. In fact, I was told by one seller's agent that it's unethical to provide this information. Less profitable perhaps, but unethical?

3) The press pumps up buyer's frenzy. Reading the papers here (before 2008), you'd think every house you walk into is going to be a multiple bid death-match, with the biggest wallet winning. Horror stories of twenty offers and final prices 30% above asking abound. Yet on the ground, this doesn't happen all that often, and there are certain segments of the market that are soft.

4) The construction cost here runs $100 to $200 per square foot. This is greater than the retail cost per-square-foot of many other regions. Labor costs may be a bit higher, as well as insurance and permits, but that much more expensive?

4) The state and communities of California use zoning laws and restrictive ordinances to help keep prices high. Land is relatively scarce, but zoning forces houses to be single occupancy. So if a decent-sized lot costs $600K, the builder has an incentive to put up the largest single family home that zoning will allow, and sell it for $1.3 million to maximize his profit. Changing the zoning laws would reduce sprawl and increase available housing, but that would negatively impact real estate values. Can't have that.

Here, the tax rate on a home is based on the last purchase price. The higher the price, the higher the tax revenues. In fact, unless I get very lucky when I finally do buy a home, I'll be paying more in property taxes than I will be paying in state income taxes.

The Sig From Hell

Yesterday I received what I thought was a social email untile I came to the following signature:

This document, and any attachments, may contain confidential and proprietary information of Really Anal Inc (RA). Any unauthorized dissemination or copying is strictly prohibited. If you are not the intended recipient, please destroy or return this document without reading or copying it, and notify us immediately. RA will protect its intellectual property rights to the maximum extent possible under law.

I'm glad I was the intended recipient, 'cause the last time I got a sig like that when I wasn't supposed to, it sure screwed up my paper shredder when I ran my CRT through it.

I'm better prepared now. Flat panel display and big honking industrial shredder. Far better to do that than to risk prison for reading an email.

I'm still wondering how I'm supposed to avoid reading the email when the sig's all the way at the bottom. Perhaps I should just delete all the emails that come from these companies, just to be on the safe side.

The Cubicle of Death

If your manager doesn't understand why cubicles are a bad place to spend your working day, then they should have to spend a couple of weeks in a Cubicle of Death. I found one when I was contracting for a mid-sized company. I thank the fates that I was only there for a few weeks.

The biggest problem is noise. The cube neighbors nattered endlessly about incredibly inane topics. When they're not talking, they liked to eat crunchy, high decibel foods like corn chips and carrots.

Very little of that nattering relates directly to work. It's about the dead bird in the driveway, or the pictures on the latest tasteless Internet site, the email joke of the day, and so on. It's best if they use a lot of obscenities. It shows they really mean what they say, even if what they say has little meaning.

If they need to talk on the telephone, they'll do so loudly. They don't really need to talk on the telephone, but their day is somehow unfulfilled if they don't. There is a direct correlation between the volume of their voice, and the degree to which the phone conversation does not relate to work. If they are talking about their hemorrhoids, they'll be practically shouting.

After noise comes the cramped, artificial conditions. No natural lighting. Windows were reserved for second-tier managers. Windows that open were reserved for the topmost executives. The furniture would be utilitarian if it was in good repair, but drawers are missing, and the ergonomic chair must have been designed for some other species.

The Libertarian Party and Big Business

A friend sent me the following link:
http://www.reason.com/0411/fe.dc.whos.shtml

So I read through it and saw all the Libertarian support, and then went back to the Libertarian site (not for the first time), and I'm left with the following quandary.

The Libertarians seem to believe that the government never has the best interests of the people in mind, or if it does, it'll screw it up somehow and cause more harm than good, but that exactly the opposite is true for businesses.

Offhand, it's hard for me to believe that the likes of say, Wal-Mart, Enron, IBM, Worldcom, Monsanto, etc, has the best interests of their employees, customers and neighbors in mind at all times, and even when they don't, they'll cause more good than harm.

Or to put it another way, for me the Libertarian Party would have more buy-in if they took the same attitude they have towards Big Government and applied it to Big Business.