Guide for Scholarly Writing


This guide is part of my Advice for Students.

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 clearer, 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").

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 research projects, is "research", not "researches". Non-native English speakers sometimes struggle with this.

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. When strictly necessary, "we aim" or "we intend" are preferable instead.

Avoid Words That Embellish Your Work

Avoid describing your results with words like "interesting", "fascinating", or "groundbreaking". Those words represent judgements that the reader should make on their own, and some readers (especially peer reviewers) will find those words off-putting.

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, a unique approach that challenges assumptions, or otherwise something that adds to our knowledge.

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 n appears after sentence n-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 Portoroj, Slovenia.

Figures and Tables

Be Careful With Line Charts

The horizontal axis of a line chart should not consist of categorical data. There are other caveats, too; if you are uncertain how to proceed, check with a senior colleague before using a line chart.

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 into the manuscript, if it contains a font size that is substantially smaller than the font size of the main body of the paper, it will be difficult for some readers to read. Increase the font size, redesigning the figure 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.

Back to Top

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

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, Or Have Solid Reasons Not To

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.

When you circulate a revised draft, it's appropriate to show specifically what has changed, so that your co-authors can focus their attention.

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.

Keep All Your Co-Authors Informed About Publication Progress

If you are the corresponding author for a submitted manuscript (i.e., the person who communicates with the publication venue), promptly forward to your co-authors copies of submission confirmations, peer reviews, submission outcomes, and other official emails. These notices will help your co-authors to understand what is happening to the manuscript and to plan for their obligations.

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.

Back to Top

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