Category: guidelines

This post is part of my ongoing scientific style guideline series.

Go to Wikipedia and start reading an article on some topic you don’t know much about. For example, the umami taste.

Chances are that by the end of the first few paragraph, you will have clicked on several links, either because they referred to terms you didn’t know (glutamate, inosine monophosphate), or because you were curious (what does Wikipedia have to say about the five basic tastes?). Now these links might be open in new tabs for you to check later. Or maybe you’ve already given up reading the original umami article, and are now exploring some new rabbit hole (e.g. the Scoville scale of spiciness).

Wikipedia is a great resource for many reasons, but one of them is this constant hyperlinking to other relevant Wikipedia articles. This has a major advantage: it allows the reader to create their own reading experience. Advanced readers on some topic can keep reading without having to go through the basics they already know. Beginner readers can look up technical terms easily. Wikipedia is a choose-your-own-adventure book, where you can wander according to your own character level.

Links are even an answer to some degree to the four-way tradeoff I wrote about here. It’s difficult to write something that is clear, brief, complex, and information-rich. But Wikipedia articles come closer to the golden middle, and that’s thanks to links. With no need to explain every difficult term directly in the text, articles can be more brief without sacrificing clarity. By packaging complex information in other articles, and showing only the link, Wikipedia articles can contain more complexity and richness of information.

(The reason it doesn’t falsify my four-way tradeoff theory is that Wikipedia as a whole cannot be called succinct. To understand a topic well, you still have to read a lot of articles. But Wikipedia packages this information in relatively brief articles. In other words, information architecture is a pretty good solution to the tradeoff.)

Links make matters easier to readers, but they also help writers. You don’t have to do as much guessing about what your audience knows; your audience will decide for themselves. And you can just reuse existing information written by others.

This suggests that our two principles are satisfied:

• Minimum reading friction: links give agency to readers. They make it easier to look up complex terms (which readers will tend to google anyway).
• Low-hanging fruit: adding links to existing public resources like Wikipedia, other encyclopedias, or open-access papers, is an easy thing to do for a writer.

Links in scientific papers

Given all of the above, we’d expect scientific papers — which are almost always at the frontier of the tradeoff, trying to cram a lot of complex information within a word limit without being too difficult to read — to use hyperlinks heavily. Right?

Nope. They rarely do. At most they include citations that link to the reference section, which may include a link to the original paper, which may or may not be openly accessible to you, and which may or may not be a 10-page difficult read in which the explanation you seek is buried in page three of the discussion with no hint to tell you where to look. And they definitely never include links to Wikipedia or anything like it.

Why is that? I’m guessing part of the explanation is the high importance of those citations. It is considered vital to put your work in relation to existing literature, so scientists have an incentive to reference as many relevant papers as they can, and no incentive to link to anything else. The respectability of the sources comes into play; Wikipedia isn’t a reputable source (it can be edited by anyone! It’s not peer-reviewed!!), nor are a lot of the other websites you could link to. So they tend to be avoided.

Then there’s the requirements of proper information management. References must be written in standard format. So if for some reason you do need to link to a website, then you’ll have to use a format like:

“Questions and Answers on Monosodium glutamate (MSG)”. Silver Spring, Maryland: United States Food and Drug Administration. 19 November 2012. Retrieved 19 February 2017.

There are good reasons to this formalism. But it also means that adding any link to a paper requires some work. As a result, I suspect it leads to less hyperlinking in science papers than would be useful to readers.

If you’ve ever read a scientific paper, it’s likely that you have googled complicated terms and looked up Wikipedia articles to help you. Scientists shouldn’t pretend that this isn’t happening. They should not hesitate to add link to resources like Wikipedia, blogs, Twitter threads, and other papers, in order to guide readers and reduce friction.

Drawbacks

There are a few drawbacks to hyperlinked text. None of them invalidate the idea that links should be used more, but we should keep them in mind.

One drawback is that links can be distracting. A barrage of links in a paragraph might be somewhat annoying to read. (Although links also have the benefit of providing novelty to text — even a simple thing like the color of a hyperlink can be useful to make a piece of writing less boring.) And having to open links may drive readers away from the original paper, and require some more effort on their part as opposed to a piece written in a way that beginners don’t need to look up extra information.

Another major drawback is link rot. A webpage may stop existing at any moment, and then your link becomes useless. Also, Wikipedia articles can change and stop fulfilling their original purpose. (Although in practice Wikipedia contributors are mindful of that and use redirections a lot.) One way to circumvent this is to link to archived pages, such as the Wayback Machine.

And of course, links don’t work offline. But my contention is that fewer and fewer people are reading papers in print or without internet access. We shouldn’t make it impossible for these modes of reading to happen, but it’s time we make full use of the web’s possibilities to improve science publishing.

Recommendations

• Do not hesitate to add links to various resources, including encyclopedias, your own content (whether formally published or not), etc.
• Try to find the correct balance between too few and too many links.
  • Your paper should be readable without clicking any links, so do explain the crucial parts directly in the text.
  • Too many links can be distracting, so choose carefully when to add one.
• Link to archived webpages when possible.
• Links shouldn’t replace formal citations, but it’s good practice to pair citations with direct links to make it easier to look up the reference.

This post is part of my ongoing scientific style guideline series.

Writing with bullet points (or bullet numbers, letters etc.) has several advantages:

• It provides clear guidance to readers.
• It forces the writer to think about the structure of what they’re trying to say.
• It comes with built-in line breaks, which tends to create shorter, more readable paragraphs.
• It breaks the flow of normal prose, which makes reading less monotonous.
• It is another channel to communicate emphasis (in addition to italics, bold, caps, subheadings, etc.).

Not everything in a piece of writing should follow point form format. Regular prose, organized in paragraphs, is better for most things. But when you are trying to express something that’s highly structured, like a list of steps (in a recipe, or in an experimental protocol), then not using bulleted lists can work against you.

Science papers being a weirdly conservative genre, bulleted lists are somewhat uncommon in them. Papers will quite often use quasi-point form formats, like (1) having numbers or letters in the middle of a paragraph, like this; (2) using “first,” “second,” “third”; or (3) separating ideas with quasi-titles written in italics or bold, but without a line break.

You see this a lot in figures. Many scientific figures are complex and contain multiple parts. Each part is identified with a letter, as in the following example from the platypus paper:

A lot of these habits come, I assume, from the fact that journals used to be available only in print. Space was very limited, and there’s often a lot of scientific information to display, so you’re not going to waste any with bullet points.

Today we don’t have these limitations. Using bullet points where appropriate is nice to your readers, so use them. They’re an easy way to reduce reading friction.

They’re also clearly a Low-Hanging Fruit. Similar to breaking paragraphs, it takes very little work to turn a piece of text into a list, if it’s already presenting the information in something close to a list. (If it isn’t, then bullet points probably won’t work well anyway.) It’s also one of those interventions that can be done almost mechanistically.

Recommendations

• Use bullet points liberally when it is appropriate, e.g. for:
  • Steps in a process, experiment, protocol, etc.
  • Lists of materials used, substances, etc.
  • Enumerations (e.g. “the five characteristics of X are : …”)
• Nested bullet points (just like the above) can be useful, but don’t overuse them.
  • At more than two levels, the information structure is probably too complex for the bullet points to improve readability.
• Pick bullet points instead of numbers/letters when the order does not matter. Pick numbers (for simplicity, prefer Arabic numerals, but Roman numerals can work) or letters when the order does matter (e.g. for steps in a protocol).
• Bullet points are useful to break the monotony of reading paragraphs, but when there’s too much point form, the reverse becomes true. Use bulleted lists less than normal prose.

This post is part of my ongoing scientific style guideline series.

Imagine you’re writing a science paper. The journal you’re going to submit it to specifies a word limit: 5,000 max. You open the stats in your finished draft — 5,523 words. You’re going to have to cut.

Problem is: everything you wrote is important! You can’t take out anything from the Methods or Results sections: that would make the study weaker and less likely to be accepted for publication. You can’t take out any of the background information in the introduction: you already included the bare minimum for readers to understand the rest.

Although, on closer inspection, perhaps not quite the bare minimum. You reread this sentence:

Most models of trait evolution are based on Brownian motion, which assumes that a trait (say, beak size in some group of bird species) changes randomly, with some species evolving a larger beak, some a smaller one, etc.

What if you removed the parts that talk about beak size? That’s not strictly necessary.

Most models of trait evolution are based on Brownian motion, which assumes that a trait changes randomly.

There we go. More concise, more to the point, and most importantly, you shaved off 23 words from that word count. Of course, the sentence is less illustrative, but whatever: your readers are smart, they’ll be able to figure out an example on their own. Right?

Wrong.

Well, okay, not quite wrong, your readers probably are smart. But this goes against the Minimum Reading Friction principle. The point of most writing, including science papers, is to do the work so that readers don’t need to. If readers need to think of an illustrative example themselves to fully understand your abstract idea, then you’re asking a big effort of them.

Picking good, concrete, relevant examples is a lot of work, whether as a reader or writer.¹Here’s an aside that’s not directly related to science but, instead, to computer programming.

When coding, you’ll usually refer a lot to developer documentation about whatever preexisting code you’re using. E.g. you want to convert a date to a different format, so you look up the docs for the function
convertFormat(someDate) -> convertedDate. The docs will describe how the function works, what its input (someDate) and outputs (convertedDate) exactly are, and so on — but very often they will not include an example of using convertFormat() in code. If there is an example, it’s often trivial and not very helpful. When I worked as a programmer, I was commonly frustrated by the lack of examples, both because I wanted to figure out quickly how to use a complicated function, and because I wanted to know about any usage conventions.

I suspect that writing documentation would be a lot more work if it included clear and relevant examples everywhere, which is probably why it’s rarely done. I realize this constantly when I write. It’s very tempting to just state an abstract idea and not bother finding a good example to illustrate it. After all, the abstract idea is more general and therefore more valuable — provided that your readers understand it.

I struggled with example-finding in this very essay. It took me a while to think of the opening about cutting examples to respect a word count limit. And I’m not even that happy with this example. For one thing, it’s not very concrete. For another, it’s not even the most common reason for lack of examples: usually, we don’t cut them out, we simply fail to come up with them in the first place.

And so, unfortunately, this piece of guidance is less of a Low-Hanging Fruit than others: adding good examples is a skill that takes some practice. At the very least, it’s not difficult from the point of view of structure, since it doesn’t require you to rethink your argument — you usually just need to add a sentence or two.

Here are a few other minor points:

Where should examples be placed relative to the main idea?

It’s most intuitive to place an example right after the idea it supports, and that’s probably fine most of the time. But there are benefits to placing an example first.

Consider:

Left-handedness seems to be somewhat correlated with extraordinary success, including political success. For example, despite a base rate of about 10% left-handedness in the general population, four of the seven last United States presidents — Barack Obama, Bill Clinton, George H.W. Bush, and Ronald Reagan — were left-handed.

vs.

What do US presidents Barack Obama, Bill Clinton, George H.W. Bush, and Ronald Reagan have in common? They were all left-handed. In other words, four of the last seven presidents were left-handed, compared to a base rate in the general population of about 10%. This suggests that left-handedness is correlated with extraordinary success, at least in politics.

I find the second version more engaging. You see an interesting fact, you’re drawn in, and then the writer tells you the more general point when you’re most receptive.

Journalists do this a lot. They opens with a story, and then proceed to make their point.

What types of scientific writing does this apply to?

Anything that deals mostly with abstract ideas. Highly concrete writing, such as the sections describing the methods or results of a study, aren’t concerned. Thus, in a typical experiment paper, this advice is mostly relevant to the discussion section and some of the introductory background.

Authors of literature reviews may need to be more careful. These papers integrate a lot of ideas from reviewed studies; it can be tempting to skip examples in order to include more content in less space. The paragraph I worked on here was from a literature review.

What about word limits, though?

Sometimes you really are constrained by externally imposed word limits, and sometimes the examples really are the the least problematic thing to take out. In those cases, well, do what you have to do.

In JAWWS, I don’t want to be strict about word limits. They often force writers to sacrifice clarity to satisfy other components of the four-way tradeoff. They’re also not as relevant in an age where papers are rarely printed on, well, paper. On the other hand, I imagine that many other publications first think that and then have to implement limits to avoid very long submissions. I wonder if the solution could be to make concrete examples not count, provided it’s not too difficult to identify them.

Recommendations

• Support each abstract idea with at least one example
  • Complicated abstract idea may benefit from multiple examples
• Choose concrete, specific examples that can be grasped immediately
• When possible, put the example before stating the underlying idea

See also

• Slate Star Codex’s Nonfiction Writing Advice, section 6 “Use concrete examples”

This post is part of my ongoing scientific style guideline series.

There are famous words from Gary Provost that go like this. Pay attention to the rhythm:

This sentence has five words. Here are five more words. Five-word sentences are fine. But several together become monotonous. Listen to what is happening. The writing is getting boring. The sound of it drones. It’s like a stuck record. The ear demands some variety.

Now listen. I vary the sentence length, and I create music. Music. The writing sings. It has a pleasant rhythm, a lilt, a harmony. I use short sentences. And I use sentences of medium length. And sometimes when I am certain the reader is rested, I will engage him with a sentence of considerable length, a sentence that burns with energy and builds with all the impetus of a crescendo, the roll of the drums, the crash of the cymbals—sounds that say listen to this, it is important.

So write with a combination of short, medium, and long sentences. Create a sound that pleases the reader’s ear. Don’t just write words. Write music.

This is legendary advice for writing sentences. It is delightfully illustrative; we grasp it immediately. And it is correct: diversity in sentence length is a necessity of good writing, just like it is for musical notes.

I claim that the same is true of paragraph length.

Science papers usually feature many long paragraphs. Often, all or almost all paragraphs in a paper are long.

Put negatively, we might call them Walls of Text. This is a good metaphor because Walls of Text, just like regular walls, serve as obstacles. They make information less accessible. How often have you looked at a Wall of Text and simply decided it wasn’t worth the effort?

Walls of Text are bad because:

1. They make it more difficult for readers to take breaks.
2. They provide no hints about the structure of the underlying ideas.

We’ll examine both in more detail below. But first I want to tie my ideas about paragraphs with my two major writing style principles.

Minimum Reading Friction: The point of having paragraphs at all, as opposed to perfectly continuous text with no line breaks, is to provide some help for readers. If you don’t do that, you’re essentially telling your readers that they’re on their own. This is the opposite of what we want — the effort should be made once, by the writer, so that the many readers don’t have to.

Low-Hanging Fruit: Cutting up paragraphs is a relatively easy task. If the sentences are structured well already, it’s just a matter of finding the “joints” in the written text where it makes sense to add a line break. If the ideas are structured in a confusing manner, then it’s more work, but there’s also greater room for improvement.

In the interest of not making this post too long, I won’t include a full-fledged example, but this past post in which I rewrote a paragraph (into several ones) is a good illustration.

1. Rewarding the reader with breaks

Humans aren’t computers. We can’t work continuously without resting. Reading science papers text is work, so we’re always on the lookout for opportunities to take breaks — sometimes microbreaks on the order of a few seconds, sometimes longer breaks like a full day.

Paragraphs, like chapters, sections, and sentences, serve the purpose of telling readers, “hey, good job, you read a thing, now you can take a break if you want.” It’s rewarding. It indicates that it’s safe(r) to take a break after a paragraph because it’ll be less work to find a reentry point later, and because you expect the next paragraph to be about a different idea.

I don’t know if it’s a coincidence that the word break is used for both concepts, but if so, it’s a fortuitous one.

Walls of Text are often bad because when they loom ahead, you brace yourself. You wonder if you’ll have the energy and time to read it all. If not, maybe you quit reading (and it’s anybody’s guess whether you’ll come back to it later). If yes, then you come out at the other end with less energy and time, and good luck if the next paragraph is also a Wall of Text. And that’s assuming you do reach the end. It’s quite likely that you quit halfway — because you had to stop to think about something you read, or you needed to look up a word, or you clicked on a link, or some random distraction outside the text grabbed your attention.

At the most extreme, you could imagine an entire book that consists of a single paragraph, with no chapters or line breaks at all.¹In fact very old books, from centuries or millennia ago, are often like that, probably because back then paper or parchment were expensive. You wouldn’t want to waste precious space with line breaks. This is really lazy on the part of the writer — the reader has to do all the work!

Now, that’s not to say long paragraphs are always wrong. Sometimes it really does make sense to package a lot of ideas together in a single Wall of Text. Also, long paragraphs can be easy to read if the sentences are good and logically connected. But this also means that if you do choose to write a Wall of Text, then you should be extra careful with how you structure the writing inside it.

2. Providing structure

Speaking of structure: line breaks are one of the most useful tools to communicate structure to readers.

We expect paragraphs to contain a single idea. You may have learned in school that a paragraph should have a “topic sentence” with additional sentences to provide “supporting detail.” This is somewhat too rigid, but the principle is sound.

The worst kinds of Walls of Texts are those that have multiple competing ideas inside them. Find where the boundaries are, and cut them up! The ideas don’t even have to be very different. Suppose you have a transition word like “Similarly” or “Alternatively” in the middle of a paragraph. The next sentence if probably closely related to the previous one, but the transition word does indicate a shift, so it’s a nice spot for adding a line break.

Of course, sometimes you really have a single idea with lots of supporting detail that it makes to sense to break up. This is why Walls of Text are sometimes useful.

In fact, as the Gary Provost quote at the top illustrates for sentences, diversity in paragraph length is a good thing.

Having only very short paragraphs is bad.

Think of low-quality newspaper pieces where there’s a line break after each sentence.

It’s jarring.

This is almost as bad as Walls of Text, from the point of view of structure.

Okay, that was annoying, right? The reason is that sentences already provide structure. So using only single-sentence paragraphs amounts to not using line breaks as an extra channel for reader guidance.

Strive to have a mix of short, medium, and long paragraphs. Heterogeneity is good. It carries more information.

Recommendations

• If you’re ever debating whether or not to end the paragraph and add a line break, err on the side of “yes”.
  • Verbatim from Slate Star Codex’s Nonfiction Writing Advice, an excellent essay whose section 1 heavily inspired this post.
• Balance your piece between short, medium, and long paragraphs.
• Cut up existing Walls of Text by finding the boundaries between different ideas.
• This advice generalizes to section breaks:
  • Err on the side of more shorter sections rather than few long ones.
  • Split sections that are long and contain many distinct ideas.

 

This post is part of my ongoing scientific style guideline series.

Textual compression techniques (TCDs) are used more and more in science writing. TCDs come in various forms, including truncation (e.g. mi for mile), acronyms (lol for laughing out loud), syllabic acronyms (covid for coronavirus disease), contraction (int’l for international), and others. The primary benefit of using TCDs in writing is to reduce text length. This is especially useful in contexts where space is limited, such as tables and charts, as well as when a long word or phrase is repeated multiple times. Another reason to use a TCD is to create a new semantic unit that is more practical to use than the long version. For instance, the TCD laser is both more convenient and more recognizable than the original light amplification by the stimulated emission of radiation.

Okay. Look at that paragraph without reading it. Does anything stand out?

I made up the phrase textual compression device and its acronym TCD. They simply mean “abbreviation,” which is what I would have used if I weren’t trying to illustrate the following points:

• Abbreviations can be distracting. Readers expect words, and things that look less like words — capitalized acronyms, random apostrophes in the middle of a word — will stand out, as does TCD above. Used sparingly, that can be good, to draw attention to something. But in large quantities, it’s jarring.
  • It’s even worse when multiple different abbreviations are in close proximity, or when similar abbreviations are used (e.g. TCRµ and TCRδ, which come up all the time in a paper I’m reading).
• More importantly, abbreviations demand cognitive effort. If the reader doesn’t already know an abbreviation (for instance because you made it up), they have to spend some energy learning it. You’d probably prefer them to expend that energy understanding your paper instead.
  • Worse, they might have to interrupt their reading to go back to where you defined the abbreviation, or to look it up online. (A nice opportunity to quit reading your paper altogether.)

Humans don’t read like computers. You can’t just “declare” an abbreviation as you would a variable in code, and assume that from now on your reader knows what it stands for. It’s quite likely that readers will skim your piece, or jump directly to a specific section (e.g. results), in which case they can miss the definition. Even if they do read it, they might forget — in a typical paper, there’s a lot of information to remember.

Of course, abbreviations can be useful, as the TCD paragraph laboriously explains. But the benefits are rather minor. On computer screens, which is where your scientific writing will almost always be read, space is virtually unlimited. (Figures and tables remain a good use case, as long as the abbreviations are easily readable in the caption.) Creating a new, more practical way to call a thing (e.g. laser) can be quite useful, but again, only if used sparingly, for important concepts.

Overall, the benefits of abbreviations are much greater for the writer than for the reader — which is exactly the opposite of what we want as per the Minimum Reading Friction principle.

The other principle, Low-Hanging Fruit, says that the best improvements are those that require little writing skill to implement. Abbreviation minimization fits the bill. In most cases, you can improve the text just by replacing the abbreviation with:

• The spelled-out version (textual compression device instead of TCD)
• A synonym (abbreviation instead of TCD / textual compression device)
• The core noun of the abbreviated phrase (e.g. device; not the best example but you get the idea. It will usually be clear in context what you refer to, unless you’re talking about many different types of devices).

Sometimes you’ll need to perform a bit more rephrasing, but rarely will you have to perform major rephrasing due to abbreviations. If you do, that’s probably a sign that the original text was awfully painful to read.

Recommendations

• Coin new abbreviations as rarely as possible.
  • If you must coin new abbreviations, make sure they’re short, pronounceable, and memorable. Don’t hesitate to repeat their meaning multiple times — you’re teaching your readers a new word.
• Generally prefer the use of spelled-out versions, core nouns, or synonyms.
• Avoid using multiple different abbreviations in close proximity.
• Abbreviations that are generally well-known, such as DNA, can be used as much as you want. A good way to tell is if they’re included in dictionaries.
• If you can’t avoid using several uncommon or new abbreviations, it can be helpful to draw attention to them, so that readers are warned that they will have a better time if they make sure they learn the new terms.
  • This could take the form of a short glossary at the beginning, making it easy to look up definitions during reading.