Although I like to think of myself as a reader-oriented science writer, there seems to be something innate in me that doesn’t always put the reader first.
It happens when I’m editing my own work. I really do try to have a reader-friendly attitude when reading over what I’ve written – “Oh, that’s not so clear, let me re-word that or add an additional sentence, a simple example.”
But other times, I just feel defensive. “What I wrote is already clear enough for anyone paying attention.”
That defensive instinct seems to pop up especially when responding to peer review. In a recent case, as I was revising an article on the connections between Bayesian inference, statistical mechanics, and Monte Carlo simulation, I was considering a reviewer suggestion to illustrate the Metropolis criterion with an example. But I’m thinking, “Does the most basic Monte Carlo algorithm of all time need to be explained again in a journal article??”
And yet the reviewer is correct. If someone hasn’t thought about Bayesian calculations before, they won’t see how the posterior simply slots into the place of the Boltzmann factor. And writing out the equation for that with a few explanatory words will only take five minutes of my time. Then it will be crystal clear. This is generosity I can afford.
Some readers will benefit from it, even if it seems elementary.
Despite my own occasional instincts to the contrary, I often preach to my group members, “Be generous.” In writing scientific text, the main ways to do this are to provide the reader everything they need to understand what you’re saying.
Here are a few tips, mostly geared to theory/methodological writing. At the beginning of your description, lay out the main ideas and use a straightforward example. This will help the reader see a little way ahead and prepare them for the technical parts. As you proceed, tell the reader exactly which equations were used – and how – to derive a new equation. Explain the logic or reasoning for each step, even if it seems simple to you. Consider presenting your equations in one or two dimensions first, followed by the more general case. And after several steps of mathematical derivation, summarize the intuition of the resulting equations.
Equally importantly, though it takes more time and effort, be generous with figures. Show things at a ‘high’ (abstract) level and also illustrate key aspects of the nuts and bolts. Show a schematic example in a simple context. A good figure might take an hour to make, but if you want your work to have lasting – and clear – impact, what better way than a good figure? While you’re at it, make more than one nice figure.
One strong recommendation I have for data figures is to avoid using a legend, especially in complex multi-panel figures. Instead, label the data/curves directly so the reader doesn’t have to refer back and forth – and lose track of the main points in all the confusion. Using the same color for data and text labels is also nice. If you feel there are too many curves to label individually in the graph itself, there’s a good chance you’re trying to plot more than a typical reader can absorb. Leave your ‘data dump’ for the supplementary material.
In summary, be generous. Keep in mind that younger version of yourself who struggled to understand challenging papers. Even your current self appreciates material that is easy to understand, I’m sure. And I shouldn’t need to point out that clearer writing serves your own interest of conveying the great work that you’ve done!