Writing

Writing is central to almost any academic activity and something I do every day, yet little attention is given to the tools and processes that enable writing to happen effectively and without throwing away your computer after trying to edit Word-files for five hours.

This tutorial covers some of the tools and processes that have helped me so far. I am still learning and experimenting and expect to update this page along the way. What this tutorial will not cover, however, is how to communicate clearly through writing. I list some books and resources that I have found helpful at the bottom of the page.

Markdown

You don’t have to use expensive and clunky software like Word to get your writing done, but it is unfortunately still the standard in my part of academia. There are ways to avoid writing your own content in Word but still get output in .docx for your colleagues and academic journals who require it. The solution is spelled markdown.

The core idea in markdown is that you, as a writer, should only have to worry about the content of your text, not the formatting. Formatting like adding italic or bold is added when you render the document but does not display in your document. For someone like me, who keep telling myself that getting the margins of the word document just so will somehow magically do the trick, markdown is a huge relief.

Another advantage of using markdown is that you can render many output formats. For example, the content for this website is written in markdown, and the same text could have been rendered into .docx or .pdf in just a few seconds.

There is an extension to markdown called RMarkdown which lets you create documents that blend text with R code. The resulting document now creates your results (figures & tables included) while simultaneously formatting the text. What a quantum leap in reproducible science!

Markdown takes 5 minutes to learn but will benefit you as soon as you write something that is supposed to be formatted to specific criteria or published to the web.

More about markdown

Markdown editors

There are several excellent choices and I recommend that you try a few of them before deciding. Here are my recommendations:

  • iA Writer - this is my favourite because it has great default options so that I don’t end up tweaking the settings but start writing
  • Ulysses - beautiful and easy to use, but I don’t like that I have to subscribe
  • Typora - very elegant UI
  • Atom - Atom is mainly used for code but can be modified to work well for academic writing
  • RStudio - If you are just getting started, the RStudio interface is an OK writing environment. I prefer other tools when I’m just writing though

Resources on writing