Guide for Scholarly Writing

This guide is part of my advice pages.

Read This Part First

Good writing means a lot to me. I created this guide for two reasons:

  1. To share my writing philosophy with students
  2. To help students avoid common mistakes that I find in drafts

This is not a comprehensive guide. If you seek one, I suggest Strunk's Elements of Style or Hacker's A Writer's Reference (oddly expensive new--get it used). I keep copies of both of these in my office. If you are a student in my lab, you are welcome to borrow them anytime.

The intended audience for this guide is students whom I work with on manuscripts, although I've written it in language to make it shareable more broadly. For my advisees, I recommend reviewing this guide before sharing your drafts, as part of proofreading your writing. You may consider printing out this guide and highlighting the parts that don't come naturally to you. Also, note that if the style guide for your target publication venue conflicts with this guide, the venue takes precedence.

I've written this guide in informal language to make it more engaging. As such, it does not always conform to the advice it conveys.

Some readers might be particularly interested in my thoughts on why good writing matters in STEM disciplines.

Finally, if you are not part of my lab and this guide is useful for you, then please email me or let me know on Twitter.

The Guide



blue flower in grass
Flower in the Sunol Regional Wilderness, near Fremont, California.

Principles to Follow

The Most Important Thing is to Write

Although my expectations are high for shareable drafts, prior to sharing you should make use of any strategy that helps you to write. Writing a messy first draft is a productive strategy for many people, who then heavily edit their work into a shareable state. If you write more easily by ignoring the guidelines in this document, then use that to your advantage, as long as you budget time later for extensive proofreading.

Find strategies that work for you to overcome writer's block (i.e., the condition of feeling unable to write). One semi-messy strategy I often use is to provoke myself with questions. My early notes for a manuscript often resemble an FAQ or a Socratic dialog.

Make Your Writing Approachable But Formal

Frequently ask yourself how much your audience will understand your manuscript if they know only the basics of your field. If there are gaps in knowledge between those basics and your work, fill them in. Write accessibly, avoiding complex vocabulary and long sentences unless they are strictly necessary. Your goal should never be to impress the reader with the level of sophistication of your writing. In scholarly writing, an efficient, elegant style is more effective than a showy, virtuoso style.

Shareable Writing is Intentional

Before you share a draft of your writing, make sure that every detail of your writing has a reason behind it. This applies to the biggest decisions (e.g., the order of sections), the smallest decisions (e.g., why each individual character appears in the manuscript), and everything in between. Although mistakes are inevitable in drafts, carelessness as a source for mistakes is avoidable.

Be Consistent

Your manuscript should reflect consistency in capitalization, punctuation, grammar, formatting, style, and all other aspects of writing. For example, you are welcome to decide whether to use the serial ("Oxford") comma, to leave one or two spaces after sentence-ending periods, to use American or British spellings, or to hyphenate certain collocations (e.g., "attention-based models" or "attention based models"), but for each of these decisions the entire document should be consistent.

Imagine Your Audience

If you get stuck searching for a way to write something, imagine speaking about it in a conversation with someone who is unfamiliar with your work. (In absence of an actual audience, I have observed that speaking out loud to an imagined person helps.) Directly transcribe what you would say, and then edit it until it conforms to the requirements for scholarly writing. Many times while meeting with students I've guided them through this process, and almost inevitably they find the words or the sentences that they needed.

Use Breaks Strategically

Stepping away from a manuscript, clearing your mind, and returning to the manuscript later resets your short-term memory and makes you a more effective editor of your work. Unfounded assumptions and idiosyncrasies become more apparent, bringing you closer to the frame of mind of a reader who is unfamiliar with your work. Their perspective, not yours, is the one you should write for.

Proofread Before Sharing for Feedback

This means carefully reading what you wrote to correct all the errors you can find in spelling, grammar, punctuation, style, and other aspects of writing. If you show someone a draft that you did not proofread, they will be uncertain which errors you will correct and which errors you do not notice. Also, a draft with fewer errors is easier to read, and it shows respect for the reader's time.

Budget time for proofreading. If you are doing it properly, it may take substantial time and effort.

Never Think Your Writing Skills Have Reached an Apex

Recognize that your writing skills should never stop improving. I also continue to improve.

Back to Top

ice spheres attached to twigs
Ice formations next to a creek in rural Nova Scotia, Canada.

Specific Practices

Define Jargon

If your work introduces a new term or uses an existing term in an unusually specific way, tell the reader as early as possible what it means. If you must use jargon before fully defining it, provide a brief parenthetical clarification.

Be Intentional With Capitalization

English capitalization rules are complex, and they exceed the scope of this guide. However, as a simplifying principle, observe that (1) all words in a name should begin with a capital letter, excluding exceptions like short words in the middle; and (2) all words in a sentence should begin with a lowercase letter, excluding exceptions like the first word and words in names that appear in the sentence.

Use Parallelism

Use parallelism, especially in lists, captions, and headings. Sibling statements should be consistent in grammar, capitalization, and style. For example, consider the following possible captions for two figures.

  1. Figure A: F-scores for Models A and B.
  2. Figure A: F-scores were calculated for models A and B
  3. Figure B: Error analysis for Models A and B, showing divergent behavior.
  4. Figure B: An error analysis for models A and B shows divergent behavior

#1 and #4 are not parallel to each other. They differ on grammatical structure (#1 is merely a noun phrase while #4 is a full sentence), capitalization ("Models" versus "models"), and ending punctuation (a period versus none). #1 and #3, however, are properly parallel.

Similarly, #2 and #3 are not parallel to each other, but #2 and #4 are.

Avoid Informal Language

Some common offenders are contractions (e.g., "it's", "can't", "shouldn't"), "and so on", "etc.", and "okay".

Many figures of speech are too informal for scholarly writing. In general, avoid using phrases that require metaphorical interpretation.

Avoid beginning sentences with conjunctions (e.g., "and", "but", or "or").

Avoid using "&" as a substitute for "and" unless it's officially part of a name (e.g., "Proctor & Gamble"). Also avoid using "/" as a substitute for "or". Exceptionally, "&" and "/" can be used to shorten text in figures or tables if space is restricted and no other alternatives exist.

Be Consistent in How You Write Numbers

Choose a numeric threshold below which you will write whole numbers in sentences with words (e.g., "There are four samples") and above which you will write them with numerals ("We interviewed 25 participants"). For example, if you write out "eight" in a sentence, "4" should not appear in any sentence; it should be "four" instead. A threshold between 10 and 20 is reasonable.

Leave Out Hedging Words

These include "rather", "somewhat", and "arguably", among others. If you are tempted to use one of these words, try simply leaving them out or find a more direct way to express your claim.

Treat "Research" Properly

Note that the plural of "research", when referring to multiple research projects, is "research", not "researches".

Invoke Trendiness Sparingly

Use "in recent years", "has become popular", and other similar phrases as infrequently as possible. The implied trendiness will not age well. "Nowadays" is particularly egregious and informal, and it should never be used.

However, sometimes it is obligatory to mention a recent trend. Simplicity is best: "recently" is acceptable if you use citations to justify the claim.

Use Granularity-Related Phrases Properly

"Coarse-grained" means less specificity. "Fine-grained" means greater specificity. Avoid using "more granular" or "less granular", which are confusing.

Avoid Aspirational Predictions

Avoid "we wish", "we hope", and similar aspirational hedging. Instead, make a specific claim about what you have done or what your work enables. When there is no alternative to an aspriational statement, "we aim" or "we intend" are preferable instead.

Avoid Vague Judgmental Language

Avoid describing research (yours or anyone else's) with words like "interesting", "fascinating", "groundbreaking", or otherwise with language that represents a vague judgement about its value. The reader should make that judgement on their own, and some readers (especially peer reviewers) will find those kinds of statements off-putting. Similarly, avoid statements like "It is important to..." or "It is essential that we...", which often imply a moral priority without supporting arguments.

If you believe your results are noteworthy, directly explain why they are noteworthy. Rather than embellishing, you should explain that you have produced the first results toward solving a problem, the best performance on an existing problem, something unique that challenges assumptions, or otherwise something that adds to our knowledge. If you believe your research is well-motivated, directly explain why.

Maintain Narrative Flow

Narrative flow is difficult to master, but it is crucial to good writing. Ask yourself often: within a paragraph, will the reader know the reason why sentence Sn appears after sentence Sn-1? The reason should be easily discernible without reading any further. A similar question applies to the sequence of paragraphs in a section.

Remember that telling the reader additional information is not, by itself, enough to establish narrative flow. You make a choice every time you write a new sentence: there are many other sentences with relevant information that you could have written instead. If the reason for your choice is unclear, you create a non sequitur, which is undesirable in scholarly writing.

To determine whether you've created a consistent narrative flow, speak the text out loud, as if you were talking to a friend or colleague. Listen closely to yourself: do you sound like you're telling a coherent story? If no, consider what you would change to make the story coherent. Did you add or reorder any words or phrases? Again, listen closely. If yes, consider changing or rewriting the text.

Your ability to judge narrative flow is one of several editing skills that improve when you step away from a manuscript and return to it later with a fresh perspective. It's difficult to detect narrative problems in text that you've just written.

Cite and Reference Properly

Direct quotations from other works (i.e., long sequences of words copied from somewhere else) should be identified with quote marks or (for longer excerpts) indented margins, as well as a citation. A paraphrased passage should not receive quote marks or indented margins, but it also should have a citation.

Citations and references should be consistently formatted. Remember the difference between a citation and a reference: a citation indicates that ideas in your manuscript originally appeared elsewhere, and a reference is an entry in a list at the end of your manuscript that provides detailed information about a source. Each citation should refer to a reference, and the inclusion of each reference should be justified by at least one citation.

The parenthetical part of a citation (i.e., the part consisting of parentheses or brackets and text between them) should not assume a grammatical role in a sentence. Consider these examples:

  1. Wilson et al. (2016) demonstrated a procedure...
  2. In a prior effort (Wilson et al. 2016), a procedure was found...
  3. (Wilson et al. 2016) demonstrated a procedure...
  4. In (Wilson et al. 2016), a procedure was found...

#1 and #2 are correct, while #3 and #4 are not. If the difference is unclear, imagine leaving the parenthetical part out: does the sentence still make sense, and does it still serve its intended purpose? For a correct citation, the answer to both of those questions should be yes.

Check out my Guide to Citations and References for more about giving credit to your sources.

Back to Top

lichen on the square top of a concrete post
Lichen on a concrete post in Portoroz, Slovenia.

Figures and Tables

Think About Your Message

When making a chart or table, think about the meaning you want to convey. What should the audience infer? Do you want to show a trend? A correlation? An abrupt change? Complexity? Aesthetics? There are other possible answers, too. Your answer should guide the representation that you create.

When making a chart, consider the options that your visualization software gives you, and make an intentional choice among them. Different chart types have different strengths and weaknesses.

Give Meaning to Figures and Tables

Figures and tables do not explain themselves. In the text, describe the message of a figure or table. Why did you include it? What should the reader know about its contents? Why is it interesting?

Avoid introducing a figure or table and immediately changing the subject. If there's truly nothing to say about a figure or table beyond its basic contents, there is no reason to include it in the manuscript.

Put Progressive or Time Series Data in Order

Data in a chart or table often contains a dimension that is progressive (e.g., education level) or a time series (e.g., dates). For a 2D chart such as a bar chart, put progressive or time series data in order. For example, bars representing different education levels should be ordered from most basic to most advanced. Similarly, follow an appropriate ordering for rows or columns in a table.

Only Use a Line Chart if You Are Certain It's Appropriate

Line charts are frequently misapplied when other chart types are more appropriate. The horizontal axis of a line chart should not consist of categorical data. There are other caveats, too; if you're not absolutely certain that a line chart is appropriate, use another chart type.

Balance Numeric Precision With Readability

Your software may produce numbers with ten places after the decimal point, but consider whether you need to show all of them in a table or figure to make your point. If not, consistently round the numbers for readability. Tables that contain many numbers each with many irrelevant digits are especially difficult to read.

A familiarity with significant figures is helpful.

Use Legible Font Sizes

After placing a figure or table into the manuscript, if the font appears to be smaller than the font of the main body of the paper, it will be difficult for some readers to read. Increase the font size, redesigning the figure or table if necessary.

If You Must Use Colors, Make Them Accessible

Some readers are colorblind. There are guides for selecting a color scheme that is attractive to both colorblind and non-colorblind people.

Eliminate Unnecessary Visual Clutter in Charts

Unless a 3D perspective is essential for your message, avoid 3D effects. Unless a color gradient conveys essential information, use a solid fill or an empty fill instead. Edward Tufte coined the term "chartjunk" to describe features of charts that distract the audience rather than helping them focus; you can search for the term to find more examples.

Avoid Misleading the Audience

When smoothing is an option for your visualization, use it sparingly or avoid using it entirely. Smoothing can mislead the audience into thinking that your data is higher-resolution than it actually is.

If you plot a trendline in a graph, show the data points that you used to create it. Without them, the audience won't know how much evidence you have for the trend.

Back to Top

dried flowers on twigs
Flowers on a mountainside near New Paltz, New York.

LaTeX

LaTeX usage is optional in my courses, but I recommend that my research advisees use it to prepare manuscripts.

Avoid Common Mistakes

New LaTeX users are often unaware of certain features:

  1. Double quote marks should be written as `` and '' to open and close, respectively. Note that both of those are sequences of two characters, i.e., neither are the "double quote mark" character on the keyboard.
  2. To produce a symbol that you can't type on the keyboard, search the web for a command to produce it in LaTeX. Special characters pasted into LaTeX code often fail to render in the typeset manuscript. For example, the Greek alpha (α) should be produced with \alpha.
  3. Avoid preparing LaTeX code in a rich text editor, like Microsoft Word. Rich text editors that alter characters as you type them often surreptitiously produce special symbols that LaTeX does not accept.
  4. Use \label and \ref to respectively label and refer to items in the manuscript such as sections, tables, and figures. These commands will manage numbering changes automatically as you edit your manuscript.
  5. Avoid using "above" and "below" to refer to tables and figures in a manuscript. LaTeX may place them somewhere you don't expect.
  6. Use % to make a line (or the remainder of a line) a comment. Do this rather than making comments that appear in the typeset manuscript; you may forget to remove them later.

Use BibTeX for Citations and References

Manually formatting citations and references is unnecessary in LaTeX, except in vanishingly rare cases. Find a guide for BibTeX and learn to use it instead. I also recommend using a citation manager like Zotero to manage your BibTeX reference collection. BibTeX code for most scholarly articles can be found on the web, but it's often sloppy or incomplete. Fix your copy when creating a reference list for a paper.

BibTeX and LaTeX are different languages. Notably BibTeX doesn't have a comment delimiter, but appending an underscore to the beginning of the name of a BibTeX field has a similar effect.

Proofread the Typeset Manuscript

It's tempting to proofread only your LaTeX code, but you should proofread the typeset manuscript (the PDF output) instead. Sometimes LaTeX won't behave the way you expect it to.

Be a Nice Person

Some LaTeX users express personal disdain toward users of other manuscript preparation software, such as Microsoft Word. Remember that using LaTeX doesn't make you a better person.

Many LaTeX users adopt the language during graduate school, but I was a postdoc when I finally learned enough that it became my default method for preparing manuscripts.

Collaborative Writing

Start Early

Give your co-authors as much time as possible to edit your drafts, so they can provide high-quality feedback. Agree to a schedule for drafts and revisions, and stick to it.

Follow Advice From Senior Co-Authors

Do not show senior co-authors (particularly your advisor) a revision of a manuscript that silently disregards any of their prior feedback, no matter how small or large. If you do this, they will think that you do not value their feedback, and they may provide you with less in the future. You should reject advice if you are certain it is wrong, but you should make sure your senior co-authors are aware that you rejected it and of your reasons.

State What Changed Between Revisions

When you circulate a revised draft, show or state specifically what changed. Do not wait to be asked for this information: provide it preemptively. Coauthors are unlikely to have the time to reread the entire manuscript. Point them to specific line numbers, paragraphs, or sections of the paper, while explaining what changed and why you changed it.

Extract the Maximum Value From Feedback

Think about the changes that senior co-authors (particularly your advisor) suggest, and assimilate them into your scholarly writing style. If you do this, in future manuscripts your senior co-authors will be able to give more attention to your ideas rather than your writing style.

Back to Top

texture of a split tree trunk
Tree trunk near Laguna de Los Tres, in Patagonia, Argentina.

Miscellany

Does Writing Well Really Matter?

"I'm great at {programming, analyzing results, getting good grades, explaining things to people, etc.}, and I wrote well enough to get to this point in my studies. Why do I need to improve my writing skills?"

As you advance in your education and your career, effective communication becomes progressively more important. In STEM fields, the problems you will be asked to work on will become more complicated or less clearly defined, or both. Components of your work will be represented in source code, mathematics, or some other medium, but ultimately you must explain your work to other people. Sophisticated work requires skilled writing to explain properly.

Your writing skills set a ceiling for how your work will be judged. Great ideas that are communicated poorly tend to be less successful than modest ideas that are communicated well. Writing that is awkward or careless interferes with a reader's understanding of content, but writing that is clean, intentional, and elegant lets the content reach its full value.

In my career, I often observe that writing well has benefits. It encourages people to work together on projects, and it makes collaboration more straightforward and less time-consuming. It also increases the likelihood of manuscripts being accepted for publication and grant proposals being approved.

How to Improve Your Writing

Practice often, by finding frequent opportunities to write. When you receive feedback on your writing, consider the reasons behind each correction and comment. Find ways to encourage yourself to be consistent and attentive to details. Read multiple genera of writing (e.g., scholarly articles, news articles, nonfiction, novels, poetry), and reflect on the differences and similarities. Identify writers whose work you like, and think about what they do well.

About the Pictures

I added them to break up the text; all of them are mine. I am a photographer in my spare time.


small plants and moss growing on a tree trunk
Plants and moss near State College, Pennsylvania.