Arnt Gulbrandsen
About meAbout this blog
2017-01-25

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.

2017-01-23

A short digression on humane architecture

This stadium was designed by Zaha Hadid and meant to be built in Tokyo:

I don't actually know, but I expect that the committee felt that it might be a landmark like the Sydney Opera House, famous, forever photographed. The committee scrapped it, though, and decided to build this, instead, and it makes me so happy:

Much more humane. By comparison, Zaha Hadid's white wonder looks like a science-fiction paperback cover. It doesn't look bad, (more…)

2017-01-20

A new email address

I think mail to आर्न्ट@यूनिवर्सल.भारत should now land in my inbox... wonder how long it'll take before the first spammer manages to spam that address.

2017-01-19

Three programs, one feature

It's not something one does often, but I've implemented the same feature in three different programs. Not very different, all are written in the same programming language for the same platform, and all are servers.

Same platform, same language, same task, same developer... you would think the three patches would end up looking similar? They did not, not at all.

The feature I wrote is is support for using UTF8 on SMTP, which I've implemented for Postfix, Sendmail and Qmail, which all run on linux/posix systems. I tried to follow the code style for each of them, and surprised myself at how different my code looked.

One patch is well-engineered, prim and proper.

The next is for an amorphous blob of software. The patch is itself amorphous, and makes functions even longer that were too long already. Yet it's half as long as the first patch. The two are, in my own judgment, about equally readable. One wins on length, the other on readability, they're roughly tied overall. This surprised me not a little.

The third is a short, readable patch which one might call an inspired hack. It's a much smaller than the others and easily wins on readability too.

It wasn't supposed to be like that, was it? Good engineering shouldn't give the most verbose patch, and the hack shouldn't be the most lucid of the three.

I see two things here:

First: Proper engineering has its value, but perhaps not as much as common wisdom says. Moderately clean code offers almost all of the value of really clean code.

Second: A small program is easy to work with, such as the MVPs that are so fashionable these days. But ease of modification isn't all, the smallest among the three servers has fallen out of use because the world changed and it stopped being viable.

Some random verbiage on each of the three servers and patches: (more…)

2017-01-07

Use UTF8 or Punycode for email addresses?

Unicode addresses in email, such as مثال@مثال.السعودية, can be written using either Punycode or UTF8. (Or, if you're feeling inventive, in another manner you invent.) Which is best?

UTF8 looks like this: From: Arabic Example <مثال@مثال.السعودية>, punycode is From: Arabic Example <xn--mgbh0fb@xn--mgbh0fb.xn--mgberp4a5d4ar>.

The answer follows from two of the design goals for the unicode email extensions:

  1. Allow UTF8 everywhere
  2. Extend email, don't restrict it

RFC 821 and its successors do not contain any rules such as you MUST NOT put the letter n next to an x, so Punycode is allowed. EAI allows Punycode by virtue of not forbidding what was previously allowed. But the right way is to use UTF8 everywhere. Use UTF8 in the subject field, in the body text, in the address… everywhere! That's allowed, it's a design goal, and it's better than Punycode for four reasons.

First, it's simpler than using Punycode in addresses, 2047 encoding in the subject text and qp/b64 encoding in the body text.

Second, it's very, very readable. A surprising amount of legacy software does the right thing if you send it UTF8, and that goes for humans who read email source too.

Third, Punycode is specified for the domain part of addresses, but not for the localpart, and if rumour is to be believed, people are using two incompatible encodings for the localpart. (In the example above, the second and third instances of xn-- are specified, but the first is not and one vendor reputedly does it differently.)

Fourth, sending Punycode habituates users to accept random hex blobs in addresses. A phisher's dream.

So use UTF8 everywhere in the message. Mapping to Punycode is necessary when doing the MX lookup in order to transmit the message, but only then.

2016-12-02

A list of free email providers

I've updated my list of free email providers and put it on github, removing many domains that no longer offer such services. freemail.txt contains a one-per-line list of domains that offer free email. There are also scripts to create the list.

2016-09-01

Code review times two

I like code review but complain about it all the time. Why? The other day I had an eureka moment: There are two quite different kinds, which I will give the misleading names agile review and waterfall review, and I'm annoyed when the reviewers perform one kind of review and I want the other.

Waterfall development is centered around planning, development and deployment in stages: First plan well and get rid of most bugs, then implement what's planned, then review and test to fix the remaining bugs, then deploy. In this model, code review focuses on catching minor bugs, ensuring code style harmony, proper use of internal/thirdparty APIs, etc. Big questions such as is this feature a good idea at all? are out of scope, because that's been settled in the planning phase. (I'm not saying waterfall works in practice, only describing the theory.)

Agile development is different. Instead of planning well, agile development is based around an iterative process: Implement something that seems to be a good idea, consider it, learn something from it, finish it and then deploy, then pick something else to do, something one now knows more about. Code review can be the first part of the consideration and learning process, so it's a good time to discover that although a feature seemed like a good idea, it's going to be a morass and should be dropped at once. (more…)

2016-08-31

Arak Al-Bustan

It is the last day of August. Tomorrow I start working, bright and early, but tonight I am still on vacation, if unpacking suitcases counts as vacation, and so I have tasted my latest bottle of arak, a variety called Al-Bustan, formerly perhaps made in Oman? There's a place called Al-Bustan there, I bought the bottle in the Muscat airport, and I haven't seen it on sale anywhere else. Formerly is formerly though, today it's made in Jordan, by the same distillery that also makes my favourite arak, Al-Zumot.

I'm glad I bought it.

Al-Bustan is nice, with a round, food-friendly taste. It's not great in the way Al-Massaya is, it just tastes of a happy occasion with good food. Oddly enough I liked it better pure than with water and ice.