Arnt Gulbrandsen
About meAbout this blog

On leaving things undocumented

I quote one of the Economist editors on their writing/linking policy: That’s the same that we do in the weekly as well — we’re not big on linking out. And it’s not because we’re luddites, or not because we don’t want to send traffic to other people. It’s that we don’t want to undermine the reassuring impression that if you want to understand Subject X, here’s an Economist article on it — read it and that’s what you need to know. And it’s not covered in links that invite you to go elsewhere. We’ll link to background, and we’ll link to things like white papers or scientific papers and stuff like that. The idea of a 600-word science story that explains a paper is that you only need to read the 600-word science story — you don’t actually have to fight your way through the paper. There is a distillation going on there. (Emphasis mine.)

The same applies to technical documentation: Stick to your subject and document that. Background information is often a digression. It adds bulk, it adds information that someone may appreciate, but quite often it adds no information that you want to convey.

How can you tell whether it's a digression in any single case? If you define the audience and goal of your text, then the goal typically answers that question. Either the text in question helps your specified audience towards the specified goal, or else it's a digression.

The digression may be something you should link to.

Dark patterns

It's still light outside, we've time for another beer.

The photo was taken four hours after sunset.

Kinds of answers

The simplest form of question is a yes/no question. How many kinds of answers does that permit?

There are eight kinds, as I count them. There's yes and no, including lookalikes like yes, in my opinion or most probably yes. This is about kinds of answers, not details.

Three more kinds of straight answers: neither, both and not 100% straight, it depends. (Some yes/no questions don't allow neither/both.)

The sixth kind is to talk about the question, for example you've heard a politician say that's a really interesting question and […More…]

Linux on a Huawei Matebook

A Huawei employee suggested to me that the Matebooks would be good for my kind of use. I want something small enough to fit comfortably on my lap, and I use the laptop as a terminal and text editor. I took his advice, bought the 2022 16GB 13" model, and it's great.

What a keyboard, what a screen, what a touchpad, what perfect linux support. That's all I have to say.

Update: The fingerprint reader is not supported by libfprint. […More…]

Rhetoric in software development

Or: Leveraging Schopenhauer's book of dirty tricks in agile software development.

This rather lengthy posting started when I read Schopenhauer's little book about rhetoric. The book is great, I particularly like the smoothly satirical preface. He describes about forty dirty tricks, and as I read I realised that I've heard every single trick in scrum meetings etc. I think some of my past colleagues would nod as they read Schopenhauer's preface: Nobody absolutely knows yet, but later, with the benefit of hindsight it may become clear that I was right today, so it's best for everyone if I have my way in this meeting.

Rhetoric (/ˈrɛtərɪk/) is the art of persuasion is Wikipedia's first sentence on the subject. When people use the word, they often don't use it to mean exactly that, though. Sometimes it means an argument or an opinionated statement, sometimes a choice of phrasing, sometimes wording with more elegance than substance, and quite often the word rhetoric is used to mean any device that's used to win a discussion except by achieving a shared understanding of the subject matter.

That isn't what Aristotle had in mind. I don't think Aristotle ever used dirty tricks such as the door in the face, the Gish gallop, guilt by association, or making jokes about other participants in a discussion.

Books on rhetoric study, analyse, categorise and explain rhetorical devices, which are means to persuade, or if not persuade, at least to carry a meeting. Today I want to speechify a bit about using the same field of study, these same devices, in three other ways: ⓐ Listening more attentively to what others are saying, noticing unfair rhetoric, ⓑ countering or neutering that unfair rhetoric, and ⓒ staying fair.

Below you'll find Schopenhauer's dirty rhetorical tricks, grouped and worded as I see it. I describe each (fairly or unfairly), mention an agile software example to help you learn to notice it when someone uses that dirty trick, and if I can, I write a bit about how to counter that trick while staying fair and within a normal software development context. […More…]

The miracle button

I read this a few years ago:

In Gurri's telling, High Modernism had always been a failure, but the government-media-academia elite axis had been strong enough to conceal it from the public. Starting in the early 2000s, that axis broke down. People could have lowered their expectations, but in the real world that wasn't how things went. Instead of losing faith in the power of government to work miracles, people believed that government could and should be working miracles, but that the specific people in power at the time were too corrupt and stupid to press the CAUSE MIRACLE button which they definitely had and which definitely would have worked. And so the outrage, the protests — kick these losers out of power, and replace them with anybody who had the common decency to press the miracle button!

So for example, Gurri examines some of the sloganeering where people complain about how eg obesity is the government's fault — surely the government could come up with some plan that cured obesity, and since they haven't done so, that proves they're illegitimate and don't care that obesity is killing millions of Americans. […] The general formula is ① take vast social problem that has troubled humanity for millennia ② claim that theoretically The System could solve the problem, but in fact hasn't ③ interpret that as The System has caused the problem and it is entirely the system's fault ④ be outraged that The System is causing obesity and homelessness and postmodernism and homosexuality and yet some people still support it. How could they do that??!

I read those paragraphs and cannot unread them. In my eyes, half the protests now look like secret or unknowing demands that someone should press the miracle button.

Someone's angry that mobile phones don't last for ten years: The manufacturers keep phone lifetimes short to boost their sales! Because they're evil! And when I read it, I think of the miracle button that the manufacturers don't have.

ZX Spectrum 40 years

I too started with that. A magnificent machine. Simple, with no chips to poke around and configure, so the only way to do anything was to write clever code.

I didn't realise how important the manual was until The Register quoted Steve Vickers, the author of the manual:

When I was writing the manual, the one thing I really wanted to avoid was the kind of brick wall that you can get to when you're just following along and then suddenly hit a wall where, unless you take on board a huge amount of understanding, you just can't make any progress. […More…]