Jamie's IMHO guidelines on writing¶

These are guidelines, not rules¶

There's no recipe for writing well, so please don't mistake my advice for "rules". My advice is advice. On a case-by-base basis, follow my advice it helps, and ignore it if it doesn't.

I plan to elaborate on the advice below with real-life examples as and when I encounter them.

Writing is hard; that's normal¶

Writing is inherently difficult. Don't be discouraged if you find it hard. I do too (and I'm a native English speaker).

Clarity¶

The three priorities in technical writing are: clarity, clarity, and clarity. If in doubt, steer towards whatever formulation seems most clear. Ambiguity is the enemy of clarity, so steer away from that.

Use technical terms consistently¶

For example, it's common to see words like "participant", "process", and "node" used interchangeably in writing on distributed systems. This may confuse the reader: are these 1. synonyms for one thing, 2. different words for completely different things, 3. different words for similar but distinct things, or 4. different words for the same thing, but which emphasise different properties of that thing?

So be aware of this and use your technical terms carefully and consistently.

Link precisely¶

If you refer to something, give an explicit link wherever possible. Thus 1. "We will see later that ..." becomes "Later on in Theorem 4.2 we will see that ...". 6. "We have already seen that ..." becomes "We saw in Lemma 14.3 that ...". 7. "In their book [citation], Benommen and Verwirrt prove that ..." becomes "In their book [citation, Section 45, Lemma 3], Benomment and Verwirrt prove that...".

You can also use choice of words to subtly link the text together (I do this quite a lot). For instance, in a long proof I may write "Assume \(X=Y\) [....] Now suppose \(Y=Z\)" (e.g. if a proof reasons by sub-cases; \(Y=Z\) and \(Y\neq Z\)). Later on in the proof I might write "Because we assumed X=Y, ...". The point is that I called \(X=Y\) an "assumption", and \(Y=Z\) a "supposition", and by means of this the reader's mind is subtly guided to the right place.

The former / the latter¶

There are IMO vanishingly few cases were using `the former / the latter' is justified. Here's one example where it makes sense:

I chewed down on the Ghost Naga pepper. It was hot. It was very hot. I was paralysed, and as I stood there with the pain rising inside my body apparently without limit, my wife and son looked on; the former with horror, and the latter with glee.

This works because it's entirely clear what the former' andthe latter' point to. However in most cases, in technical writing, you're better off just inlining the pointers:

Chili peppers are edible by both birds and humans. However, the former are not sensitive to capsaicin whereas the latter are.

becomes

Chili peppers are edible by both birds and humans. However, birds are not sensitive to capsaicin whereas humans are.

Pick a voice, and stick with it, and be clear on who is acting (and why)¶

This is not a good sentence!

We see that one can obtain \(1/2\) if you input \(2\) into \(\lambda x.1/x\), but it is recommended to use a constant \(1/2\) directly instead.

It changes voice (through "we", "one", "you", passive voice), and more insidiously it doesn't specify * who does the recommending (the author? an international standard? a convention in this codebase? something else?) --- * or why the recommendation is made (simpler? quicker? something else?).

Here's a better version (one of many):

You can obtain \(1/2\) by inputting \(2\) into \(\lambda x.1/x\), but in this case we would suggest to simply use a constant \(1/2\) directly instead.

(Sub)section titles should be meaningful¶

A section on widgets should have a section title that includes the word "widget". This makes it easier for the reader to find the section on widgets, just by looking at the Table of Contents.

(Sub)sections could start with a mini-intro, to establish narrative¶

I often like to start a (sub)section with an introductory paragraph of the form

Recall that in Subsection 1.2 we proved that widgets are isomorphic to wombats. We will now exploit this isomorphism to build a duality between widget-nuts and wombat-bolts. The culminating result is Proposition 1.2.4 (which we will use later to prove Theorem 2.1), and the technical heavy lifting is done by Lemma 1.2.3.

Often text like this can feel a bit repetitive, especially if there are several subsections, but if so I still think this is preferable to losing the reader.

Define (nearly) everything¶

Don't be afraid to define things. Distributed system? Say what that means to you. Forking? Explain it.

I get this all the time with papers e.g. that mention first-order logic without saying what that means to the author. But there are several flavours of first-order logic (with or without equality; with or without term-formers). If it's a paper on complexity theory, there may be an orderability axiom floating around. This can all make a difference. So as a courtesy to the reader, I suggest to spell it out.

For example, when I talk about posets (which I probably do more often than the national average!) I introduce them like this:

Let \((\mathsf P,\leq)\) be a poset (a set with a reflexive, transitive relation).

Some referee will always complain that "You really don't need to define what a poset is". That's wrong. I do, because it might help that one reader who isn't an expert in logic to understand just a bit more of the paper, and that's a Good Thing. (Plus, I keep getting posets mixed up with partial orders, so it helps me to remind myself of what I'm assuming.)

Definitions in normal font, results in italics¶

It's up to you, but in LaTeX I like to follow a standard that * An environment in which something is defined or discussed (like {definition} or {remark} or {proof}), goes in normal font. * An environment in which something is claimed (like {lemma}, {theorem}, or {conjecture}) goes in italic font.

Use enumerated lists¶

Technical writing is full of lists; use them. Usually you should enumerate lists (not itemise them), so that you (or your reader, if and when they cite you) can easily refer to specific list items.

This paper has two main goals: to define widgets and to describe their applications to wombats.

becomes

This paper has two goals: 1. We define widgets (see Sections~\ref{sect.widgets}, and~\ref{sect.advanced.wombats}). 2. We apply them to wombats (see Section~\ref{sect.wombats}).

Here's another example:

Our guide decomposes into three sections. In section one we ask what are blogposts? We answer the question, then discuss types of blogposts and some differences between blogposts and formal communication. Next, in section two we review methods and techniques for writing an effective blogpost. We enumerate the steps to success, taking the reader from idea to published blogpost. Thereafter, in section three we discuss additional best practices for writing a blogpost, navigating the process of writing, and dealing with writer’s block.

This would be better as follows:

Our guide has three sections:

In section one we discuss the types of blogposts.

In section two we discuss techniques for effective writing; from first concept to finished blogpost.

In section three we discuss more advanced techniques and how to deal with ..... writer’s block.

If your list items admit a natural ordering, list them in order, state the order, and state whether it's increasing or decreasing. Usually, you should put the most important thing first. E.g.

There are three reasons not to leave dirty dishes in the sink (items in decreasing order of importance):

It needs to be done, so you might as well do it now.

Dried-on food is harder to get off.

If you need to prepare food in a hurry, your sink will be clear and ready.

Include jokes¶

There's no harm in the occasional joke, so long as there's no risk of causing confusion. E.g. above, I slipped in some meta-textual humour about .... writer's block. That's fine.

Define terms in bold font¶

When you introduce a term, put it in bold font at the site of definition. For example:

Definition 1. A residuated lattice is a lattice such that \(\ast\wedge y\) has a right adjoint \(y\to\ast\).

This helps the reader looking for where a term is defined, to find it by scanning (rather than reading) the text.

1 paragraph = 1 idea¶

This is a big one. If your paragraph contains two ideas, it's two paragraphs. See edited text in Get to the point below.

Give things names¶

If you talk about some entity like "an agent" or "a regulator" or "an input" or "a message" and then refer to them later in some meaningful way, a useful trick is to give that entity a name. So for example "an agent" becomes "an agent A". Then later you can write "... the agent A" and it's clear to what you refer. See edited text in Get to the point below.

Get to the point¶

Lead on the main point. Consider this text (adapted from here):

Motivated by decentralized permissionless protocols that are ultimately backed by social consensus, which can only perceive and act much slower than the service provisioning, we study what we term a Slow Game; a type of principal-agent problem, in which the agent acts as an operator of a service and the principal as a regulator, which sets and attempts to enforce policies on the service being provided. The regulator is slower acting and measuring than the operator, which introduces uncertainty depending on the difference in speed. In this publication, we introduce a framework inspired by lossy compression problems to model this type of game, as well as present results from simulations of a minimal example. Even though this work was inspired by systems where loss is induced by speed differences, it should apply to other setups in which a principal makes lossy observations of a world state influenced by an agent.

Here's a simple edit to lead on the main point, and to insert paragraphs and lists:

A Slow Game is a scenario in which a fast agent A is providing services while a slower regulator R samples A's output to check QoS (quality of service). <- idea 1

Because R's sampling of A's behaviour is lossy, some uncertainty is inherent in this scenario. R needs to extrapolate from its sample to infer actual behaviour, and furthermore, A knows this fact and might exploit it to cut corners undetected. <- idea 2

In this document, we will: 1. introduce a rigorous framework inspired by research into lossy compression [citations], to model the slow game such that we can reason about the relationship between sampled behaviour and the most likely actual behaviour; 1. use our framework to design (and prove properties of) policies to align the incentives of the fast agent A with the slow regulator R, as much as possible; and 1. we present the results from the empirical simulation of a minimal but representative example. <- idea 3

We focus on systems where information loss is induced by speed differences, but our techniques plausibly could also apply to other setups in which a principal makes lossy observations of a world state influenced by an agent. <- idea 4

Be concise¶

Readers are busy and attention dies off as \(1/l^2\), where \(l\) is the length of the text. Thus, a text that is half as long is roughly four times as likely to be read.

Every word you can remove without impacting meaning, is a step in the right direction!

More later¶

I'll add more stuff as it occurs to me. I welcome questions, corrections, and requests.