We write a lot as scientists. We write emails, we write grants, we write presentations, we write papers. We also write a lot as academics. We write lecture notes and slides, we write course outlines, we write tutorials. The tool we use to write these various forms of communication is to some extent up to us, but it also depends on who we are working with and the formal requirements for a given document.

For many of us, Microsoft products – Word, Powerpoint – are the obvious choice for all of these tasks. But there are other options, really.

When all you have is a hammer, everything looks like a nail

Alternatives for scientific and academic writing

As previously mentioned, it is possible to write academic papers -and student theses- using typesetting programs such as LaTeX. There are many advantage to using LaTeX to write documents. It is a simple text file, so there’s no chance it contains viruses or hidden nasty computer bugs. And because it is a simple text file, it is easy to keep under version control, something that is near impossible with a Word document. However, there is a bit of a learning curve with LaTeX and all the in-line commands and functions can be distracting and intimidating at first. Also, people from the life, health, and medical sciences are usually less (or not) familiar with LaTeX, which can be a deal breaker when you are trying to write a paper collaboratively with colleagues.

Another option is to use LibreOffice and .dot files. This too is not all that common because co-authors, journals and even funding bodies often request Microsoft Word .docx files. Unfortunately, such files cannot be put under version control. Moreover, depending on who opens the file – a Mac user, a Linux user, a Windows user – the formatting may look different or even get messed up. Worse yet, for people who use software like Endnote to manage and input references into Word documents, the links to references can be jumbled (or completely lost) when someone opens up the document on a different operating system.

Markdown is a lightweight markup language with plain-text-formatting syntax. Without realising it, you have likely already seen Markdown in action. For example, most Github repositories include a README.md file that is presented very nicely on the project’s homepage. This is what I did for my two Python packages: Pliffy and Spike2py. Markdown files can easily be converted to many output formats using a program called Pandoc. These formats include Microsoft Word and Powerpoint, LaTeX, PDF, HTML, plain text and various browser-based slide show format (e.g. slidy, reveal.js). Given its simplicity and versatility, Markdown seems like an interesting option…but is it powerful enough to be used for all the tasks academics and scientists do?

This blog series will hopefully answer this question.

A first introduction to Markdown

Below is screenshot of a Markdown document (left) and how its most simple rendering (right).

Summary

Markdown is a simple markup language that, for scientists and researchers, represents an interesting alternative to Microsoft Word and Powerpoint. This might be apparent given the simplicity of the example provided above, but hopefully by the end of this blog series you will be convinced of the usefulness of Markdown.

In our next post we will learn how to use Markdown and Pandoc to keep notes about an ongoing study.