Association for Biology Laboratory Education

Using Markdown, R Studio, and free tools to write, publish, and share an open-source scientific writing guide
    

A. Daniel Johnson

Advances in Biology Laboratory Education, 2023, Volume 43

https://doi.org/10.37590/able.v43.art10

Supplemental Materials: https://doi.org/10.37590/able.v43.sup10

Abstract

One of our essential tools for teaching scientific writing in multi-section introductory biology courses is a standardized Scientific Writing Resource Guide that students and instructors can use across multiple courses. We have published our Writing Guide as an open-source book that others can modify to meet their individual needs. To simplify conversion between different formats, we wrote our Writing Guide using Markdown. This lightweight markup language lets authors write text once, then output it in a variety of formats such as HTML5 for web pages, or Word/PDF documents for handouts. Groups of Markdown files can be combined to create interactive online books. Markdown takes ~20 minutes to learn, and marked text remains easily readable. These features make it ideal for writing lab materials. Participants in this workshop do not need any prior technical knowledge beyond basic computer skills. They will learn to write with Markdown by editing existing pages from our Guide and creating new pages. They also will convert Markdown files into formatted Word and HTML5 documents. We will demonstrate how to use R Studio to assemble collections of Markdown documents into books, and how to use GitHub to manage and share writing project files. Participants will leave with a complete copy of our Scientific Writing Resource Guide that they can revise to match their course requirements, plus the tools for converting Markdown files to their preferred format. They will have a starter book template for R Studio that they can use to write and compile new book projects of their own.

Keywords:  R-studio, scientific writing, R Markdown, writing guide, web publishing, lab development tools

University of Victoria (2022)