This document is a collection of best practices and common pitfalls that I've encountered over many years of writing and editing scientific publications.
The manuscripts that we publish will use the same "house writing style" to maintain consistency and readability. In addition, this document describes the tools and workflows that I've refined over the years for smooth scientific authoring.
Please use this as a checklist to hone your own writing. Get in the habit of identifying and fixing these common pitfalls during your writing practice to become a more efficient writer.
Table of Contents
We author documents in Overleaf, a phenomenal LaTeX editor. Think of Overleaf as the "Google Docs of LaTeX."
Tip
UT-Austin provides a premium subscription for all staff.
To start a manuscript, we will clone a skeleton Overleaf project that has a generic manuscript setup.
TODO: Describe what a skeleton project typically looks like
-
Professional typesetting: LaTeX produces high-quality typesetting and formatting, making your document look more professional and polished. It provides consistent formatting and layout for the entire document, including headings, equations, tables, and references.
-
Math and scientific equations: LaTeX excels in handling mathematical and scientific equations. It has built-in support for mathematical symbols, formulas, and equations that are commonly used in academic writing.
-
Version control: LaTeX documents are plain text files, which makes them well-suited for version control systems like Git (and Overleaf). Multiple authors can collaborate and track changes without all the nonsense of versioning via filenames (i.e., Manuscript-FINAL-FINAL-v2.1.docx). Git makes it easy to revert to previous versions or merge conflicting edits.
-
Cross-referencing: LaTeX allows you to reference sections, figures, tables, and equations easily and automatically. This is particularly useful when writing long documents, such as manuscripts, grants, and theses.
-
Work in your favorite text editor: I prefer to write in GNU Emacs. You may prefer Neovim, VS Code (💩), Overleaf, or something else entirely. With LaTeX, we can all work in our preferred editors where we've (hopefully) learned to be efficient.
-
Most importantly, writing in LaTeX separates formatting from content-generation. By writing in plain-text, we can focus on the substance of our writing and not the formatting. In comparison, just note how much time you spend formatting fonts, margins, and other nonsense in MS Word.
- Include a space between a digit and its unit:
- In
0.5mM IPTGshould be0.5 mM IPTG
- Use appropriate Greek characters for units:
5 ulshould be5 μl
- Consistently write units that are per unit time or volume. Do not switch styles, as per the example below. I weakly prefer superscripts in the example below.
The buffer flow rate was 100 µl/min for all washing steps. or The buffer flow rate was 100 µl min-1 for all washing steps.
- Be consistent about how you report time units in figure axes and
methods sections. Decide ahead of time if you're using
hours, min, secorhr, m, s. I prefer the first, as its a bit more descriptive.
O.D. of 0.6-0.8should instead be OD600~0.6-0.8
Report temperature in Celsius as follows. Note that there is a space between the digit and the degree symbol (˚). Include the degree symbol, it is not optional.
Cells were grown at 18 ˚C for 4 hours.
Do not report centrifugal force in revolutions per minute (RPM). This unit reports how fast the centrifuge is spinning, but is meaningless without knowing the rotor type, angle of rotation, etc. Instead, report the relative centrifugal force (RCF), which refers to the force exerted directly on the sample. Most centrifuges will report the RCF when the rotor setting is set (or ifs a single rotor centrifuge).
- Gene names should be lowercase and italicized.
CRISPR-transposons do not encode the adaptation genes cas1 and cas2.
- Human protein names tend to be ALLCAPS (e.g., DNA2), whereas yeast and other organisms are Upcase (e.g., Dna2).
- When discussing point mutants, define the mutation at least once using the following convention: NAME(from###to). For example:
A helicase-deficient DNA2(K654R) mutant decreased resection processivity and velocity.
Most importantly, keep the gene and their corresponding protein names separate. That is, do not confuse cas1 (the gene) and Cas1 (the protein) in your writing.
Define organism names, especially when referring to enzymes that were sub-cloned from these organisms. Include at least one definition in the main text—introduction or results—and another in the methods section.
Here is an example from the methods section of a paper:
The gene expressing Eubacterium siraeum Cas13d (Es Cas13d) was synthesized (IDT) and cloned into …
| BS3 | bis(sulfosuccinimidyl)suberate |
| cryo-EM | cryo-electron microscopy |
| CVs | column volumes |
| DAP | diaminopimelic acid |
| IPTG | isopropyl β-d-1-thiogalactopyranoside |
| LB | lysogeny broth |
| MBP | maltose binding protein |
Note to self: Use C-c ^ to sort the org-table
We commonly use the following words in our writing. Please stick with these conventions:
| Correct usage | Incorrect |
| flowcell | flow cell; flow-cell |
Code and some supplemental resources are shared via the Finkelstein Lab GitHub page.
To add to our repository:
- Create your own GitHub account.
- Create a private repository that will summarize the project. Do not make the repo public unless we're ready to release the manuscript.
- Include a descriptive readme.md file. The file should describe the main goals of the project, what each module does, and how to cite the resulting manuscript. If the manuscript isn't online yet, include a placeholder or link to bioRxiv.
- Let me know when we're ready to make the repository visible. I will fork it to our official GitHub mirror.
The gene expression omnibus (GEO) is an international public repository that archives and freely distributes microarray, next-generation sequencing, and other forms of high-throughput functional genomics data submitted by the research community.
- If your manuscript is re-analyzing prior published date, double check whether its been submitted to GEO. Include GEO accession numbers in a supplemental table.
- If your manuscript includes new sequencing data that falls within the GEO mandate, upload it to GEO and report the accession numbers in your manuscript.
The lab is transitioning to the free, cross-platform Inkscape as a drop-in replacement for Adobe Illustrator.
Inkscape has nearly the same functionality, exports standard SVG files, and a robust bookmarking system.
As a bonus, Inkscape has a convenient command line interface for adjusting graphic sizes and formats.
For example, the code below will export an svg figure into a png with a white background:
inkscape -b FFFFFF -h 1024 -d 300 input.svg -o output.png
TODO: I need to test the CLI at some point
You can use the template below to start designing your figure. It also includes guides for various figure widths, ranging from a single- to 1.5- and two-column formats.
Below are a few pointers on designing clean and consistent figures:
- Keep figure axes and legends consistent
This is a vast topic that cannot be fully explored within the scope of this document. For a concise treatment, please read the following key sections of Claus Wilke's excellent book, Fundamentals of Data Visualization.
- Color Basics
- Claus Wilke's presentation on using colors: color scales
- Check out the Okabe-Ito scale, which we use frequently in our figures
- Common Pitfalls of Color Use
| Name | Hex code | R, G, B (0-255) |
| orange | #E69F00 | 230, 159, 0 |
| sky blue | #56B4E9 | 86, 180, 233 |
| bluish green | #009E73 | 0, 158, 115 |
| yellow | #F0E442 | 240, 228, 66 |
| blue | #0072B2 | 0, 114, 178 |
| vermilion | #D55E00 | 213, 94, 0 |
| reddish purple | #CC79A7 | 204, 121, 167 |
| black | #000000 | 0, 0, 0 |
Papers that are authored in LaTeX use BibLaTeX for formatting citations.
BibLaTeX is a modern, mature, and highly capable software package. However, you
probably don't want to write the references.bib yourself! Luckily, Zotero
makes it easy.
The easiest way to integrate citation management with our project is to use the free Zotero citation management software. Zotero can be syncronized with the Overleaf project. For a tutorial, see: How to link your Overleaf account to Mendeley and Zotero.
Important
Zotero->Overleaf sync in only one way. You cannot edit the .bib file directly. Also, only the person that set up the sync (usually the Overleaf project owner) can trigger a re-sync.
Here is the best workflow that I've found for working around the limitations of Zotero-Overleaf sync.
- Install the standalone Zotero app (Zotero | Downloads)
- Install the Better BibTeX for Zotero plugin
- Change the BetterBibTex citekey to match how Overleaf imports citations into
Zotero
- In Zotero, go to
Zotero Settings > Better BibTex > Citation Keys - Set the citation key formula to:
auth.lower +'_'+ shorttitle(1,1).lower + '_'+year - screenshot:
- In Zotero, go to
- Change the
Zotero Quick Copycommand to use BibTex citation keys- In Zotero, go to
Zotero Settings > Export > Quick Copyand select `Better BibTeX Citation Key Quick Copy'
- In Zotero, go to
- (Optional) If you're working on existing repo, you can select all references
and run the
Refresh BibTeX keycommand. On Macs, it is available by clicking the second mouse button when hovering over the references pane.- the end result should be a new field for each reference that looks like
this:
- the end result should be a new field for each reference that looks like
this:
At this point, you should be able to drag and drop citation keys directly into
Overleaf. Example:
Tip
The Overleaf project owner still has to "import" the references from Zotero to Overleaf. You won't see the proper citation until this happens. But when the bib file is updated, all citekeys should be formatted automatically.
- Bibliography management with biblatex - Overleaf: This is an excellent tutorial that covers the basics of working with BibLaTeX files. I highly recommend this tutorial.