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.