Audience and goal

Written texts have two major invisible properties: audience and goal. I can't remember who taught me about that, but I taught it to my friend Abhijit Menon-Sen when we started working together, and the texts he and I have written together over the years always have a hidden comment describing the audience(s) and goal(s) for that text. That's why those texts are crisp and to the point.

Here's an example. Not by us together, this one is his alone.

Abhijit and his girlfriend Hassath have recently built a house, it's aaaaalmost done now, and a few weeks ago Abhijit wrote a blog posting about an electric power gadget they bought for the house. The audience for that posting consists of two groups of people: Friends who want to know how the house is coming along, and people who are searching for reviews of the gadget before possibly buying one themselves. The goal for the first group is to describe the power problems and how Abhijit and Hassath are coping, and for the second group, to tell them whether and how well that particular gadget helps with that kind of power problem.

Now please read about their amazingly unreliable power supply and consider how each sentence, each paragraph and each picture helps with either or both of those goals, in the eyes of those audiences. Does a sentence say something that both audiences already know, or does it tell either or both audiences something Abhijit wants to tell them? Does a sentence help with one goal but disturb the other? What does the photo achieve? Would mentioning the audiences or goals in the text help to achieve either of the goals, or would it distract or detract?

That posting may be stylistically vapid, but it achieves Abhijit's goals and that makes it good writing. The rest is a mere question of how good.

Now please start formulating an explicit audience and goal before you write your own email, documentation, almost anything. Help save the world from pointless blather and documentation that forgets the critical points.

Reviewing code and people

Some years ago an Indian friend of mine was invited to speak at a conference here. He applied for a visa, then the visa application was rejected. He got someone to phone around behind the scenes, and learned the real reason for the rejection.

The decision made sense.

My friend was an expert in his field and could easily get a job here. The fact that he was invited to speak at that conference proved his expertise, and his connections here proved that he could easily get a job. Further, my friend was single (on paper), did not have a highly paid job in India, and he was young and easily able to move. The visa application reviewer quite sensibly inferred that that my friend had the option of not returning.

The visa application reviewer used this decision matrix when processing the application:

This matrix leaves out the impact on the conference and on my friend, because their interests did not matter when the decision was taken. The government at the time really wanted to reduce the number of people who overstayed their visas, and almost ignored other factors when it made the decision matrix. It didn't particularly care to please my friend, or to displease him, it wanted to reduce the number of overstayers.

It's easy to curse the xenophobic so-and-sos who guard borders, but when I look at that matrix, I can understand why the reviewer decided to reject the application, if the chance of overstaying seemed even just a little above zero.

Code reviews are like that in some companies. They can be easy to curse, too.

Given that matrix, of course each and every meeting is more important than getting progress on the patch. Of course any minor objection is enough to block the patch or ask for another revision. Some people say things like if you haven't found any problems, you haven't reviewed properly. I think that when someone can say that with a straight face, the team is secretly using the decision matrix above.

For the next visa application my friend changed the matrix. Among other things, he arranged for a Sir Humphrey Appleby to telephone the consulate and explain that the minister hopes you will treat this young man favourably.

My friend got his visa. It's always good to have friends in the foreign ministry. It's good to have an appropriate decision matrix, too.

I have no simple hack to balance the matrix for a code review. But balance is necessary, that's one of the keys to useful code reviews. If the matrix is skewed one way, the code will stall, if the other way, it will acquire too much technical debt.

Code review, Gerrit's way

To the New Yorker, this is a neat way to start a story: A few years ago, at a Las Vegas convention for magicians, Penn Jillette, of the act Penn and Teller, was introduced to a soft-spoken young man named Apollo Robbins, who has a reputation as a pickpocket of almost supernatural ability. Jillette, who ranks pickpockets, he says, a few notches below hypnotists on the show-biz totem pole, was holding court at a table of colleagues, and he asked Robbins for a demonstration, ready to be unimpressed. […More…]

No mail today

I am reminded of the Inmos Transputer.

That, as my older readers may still vaguely remember, was a freak processor in the eighties. It was designed for parallelism: Its fundamental design was for a computer with many transputers, not one with a single humongous blob. Each CPU was small, simple (the wikipedia page includes the complete instruction set) and linked to four other CPUs using bidirectional message-passing connections, and the design allowed vast CPU meshes with message routing and forwarding.

The thing that reminds me of the transputer is the way those links worked. When a Transputer received a message that had to be forwarded, it would prioritise communication over its own computation.

I am reminded of this because my mail is down. A great big failure happened during Christmas vacation. Then a routing mishap left me unable to take part in a video conference this morning. I am forced to prioritise my own programming over message passing, and it feels so good. Yesterday was great.

Tomorrow I shall apologise to borud about my unresponsiveness. But today, I plan to wallow in solitary hacking.

Actually I'll wait a few hours with publishing this. There's a chance someone might see it.

Hard work vs. silver bullets

Blog posting number one, from a typical silver bullet merchant […More…]