Overleaf

We usually write our papers in LaTeX on Overleaf. With your EPFL email address, you can upgrade to a professional account for free, so you can use Dropbox and GitHub integration, change tracking, private projects with invitations, and more.

Macros

When writing in LaTeX, you should make ample use of macros. Instead of typing the same commands over and over again, define a concise macro once and then reuse it. Not only will this save you time, it will also make it much easier to apply consistent changes quickly: just change the macro definition, and voilà.

Some of the macros that we end up using all the time at dlab are available in dlab_macros.tex, available here. Include this file in all your LaTeX projects by adding a line \input{dlab_macros} right after the \documentclass command. Make sure you become acquainted with the useful macros defined in that file. They will make your life easier!

Writing style

  • A short and sweet compendium of tips for writing technical papers by Stanford’s Jennifer Widom. Before you take a deep breath, roll up your sleeves, and start writing a paper, revise this document. The bit about the intro has been particularly useful.
  • Writing the introduction is particularly challenging. Some key questions that you might consider answering in your introduction are given by “Heilmeier’s Catechism”. These questions are actually not only useful when writing up your project (i.e., after finishing the project), but also at the onset of the project, or even when brainstorming about new potential projects. They’re tough, existential questions, and if you can answer them affirmatively, you’re setting yourself up for success!
  • A brief masterpiece, Strunk and White’s The Elements of Style is a must-read if you aim to improve your writing. A free version is available on the Internet Archive.
  • Check out this Nature article for advice on producing a manuscript that will get published and pull in readers.
  • Ten Simple Rules for Structuring Papers
  • Ten Simple Rules for Writing Research Papers

Error analysis

One common feature of outstanding papers (among those that are primarily concerned with proposing a new method to solve a certain problem) is that they don’t just propose a new method, but they also give nuanced insights into situations in which the method fails. This is called “error analysis” and should be included in all method-centered papers. Here is a nice post that summarizes some key ideas.

How to embed fonts

Publishers (e.g., Sheridan, AAAI Press) regularly complain about fonts not being embedded properly in the camera-ready PDF. Usually PDF images are the culprits.

If the plots are made with R, the simplest solution is to use cairo_pdf() instead of pdf().

If you are not using R, you may use the embed_fonts.sh script available here in order to properly embed fonts. You need to run the shell command sh embed_fonts.sh FIG.pdf once for each image (e.g., FIG.pdf) that you want to include in your paper. The script will modify the image by embedding all fonts. Then you should use the modified images for compiling your final version of the paper. Note that you should not just run embed_fonts.sh on the full-paper PDF, but you need to run it on each image separately before making the final full-paper PDF. Otherwise you may get horrible results, with entire pages looking grainy, also when printing the paper on a physical printer.

A random list of tips and best practices for writing

This list is incomplete and may be expanded:

  • Words that contain a hyphen (e.g., “government-mandated”) will be split across lines by LaTeX only at the position of the hyphen; consituent words will not be split (e.g., you could not get “govern-“ on line one, and “ment-mandated” on the next). This can often lead to overfull lines – ugh! Instead, use the \hyp command from the hyphenat package (already included in dlab_macros.tex). For instance, instead of government-mandated you should use government\hyp mandated in LaTeX. Yes, it looks ugly in the source code, but can avoid displeasing results in the compiled PDF.
  • Do not flip back and forth between tenses. Stick to either the present tense (“we run the model 5 times”) or the past tense (“we ran the model 5 times”).
  • Don’t make inflated use of capital letters! Do not use title case for section and subsection headings, figure titles and axes, table columns etc. For instance, don’t name your section “Data Collection Procedure”, but “Data collection procedure”. Save title case for the paper title only.
  • Use the Oxford comma. For instance, write “Germany, Austria, and Switzerland”, not “Germany, Austria and Switzerland” (but of course it will still always be “Germany and Austria”, without any comma). In principle, it doesn’t matter if you use the Oxford comma or not, as long as you do it consistently. In practice, it is much easier if we all follow the same rules, especially when multiple people collaborate on the same paper. So always use the Oxford comma.
  • Structure your paper well. Long sections or subsections can become more reader-friendly when you name important paragraphs via the \xhdr command from dlab_macros.tex.
  • If your bibliographic style uses numeric references (e.g., “[1]”), you should not use code such as as shown by \cite{xyz}, since this would lead to the ugly “as shown by [1]” (how would you read this out loud?). Instead, you should write as shown by Smith et al.~\cite{xyz}, or even better (if the \citeauthor command is defined) as shown by \citeauthor{xyz}~\cite{xyz}.
  • References must be in a consistent format. It’s not enough to just copy-paste from Google Scholar. You must personally go over the BibTeX file to make sure all items appear consistently in the PDF. Here is an example of a consistently formatted bibliography. An incomplete list of questions you should ask yourself: Are titles consistently capitalized? Are conference names printed consistently in either abbreviated or full form? Does the same conference/journal always appear under exactly the same name? Are journal/conference names appropriately capitalized? Are page numbers given for all journal papers?

Once your paper has been accepted 🎉

First, put your feet up on your desk, reflect on what you’ve achieved, and enjoy an uplifting beverage of your choice. Great job!

Second, capitalize on the great work you’ve just wrapped up. Don’t just upload your paper to the website and wait for others to notice. With some active PR, you can get much more attention from a wider audience. To make things easier, we have a post-acceptance paper checklist for keeping track of the required steps. The key steps are these:

  • Start working on your camera-ready version right away. Don’t wait with it until the last minute. Give your adviser enough time to make a thorough pass, just as with the original submission (but this time for real…).
  • Give the LaTeX source code of your camera-ready version a permanent home in our paper repo on GitHub. Overleaf is great for writing, but it’s a “hot”, high-frequency environment. The source code lasts longer in a “cool”, low-frequency environment such as GitHub.
  • Upload your paper to the arXiv. This helps even once the paper has been accepted and published (i.e., even once it’s not a pre-print anymore): the arXiv newsletter has many and various subscribers, including journalists.
  • Write a blog post. Making your work accessible to a broad audience is key, and blog posts (a.k.a. dlog posts) are well suited for this purpose. Every paper must be accompanied by a dlog post; it’s not optional.
  • Publish your data whenever you can. It’s a great way of getting citations for your work, and it increases reproducibility and accelerates the pace of science. Small datasets can be published on GitHub, for larger ones you can use Zenodo.
  • Publish your code as a repo in the dlab organization on GitHub. Even if the data cannot be published for some reason, there’s usually no reason not to publish code. Public code increases transparency and will allow others to reuse (and cite) your work – everyone wins!
  • Talk about our work on social media, e.g., on Twitter. It really can make a difference. Tweets will of course be most powerful when they can already link to the dlog post, so people don’t have to read the entire paper, but can learn about it in an entertaining and inspiring few minutes.

Granted, these steps add quite a bit of work, especially when one would just like to kick back in celebration of having a paper accepted – which you should definitely do! But then put your boots back on and walk the extra mile – it makes a difference!