Writing Guide

Writing Guide

The purpose of this guide is to provide an approach to writing that parallels the path of your research to improve efficiency and allow for reproducible research.

  1. Create a Github Repository for your research

    1. Create Repository

    2. Use Github Desktop to clone to your local computer (store in Documents->Github)

    3. Open project in RStudio (version 2022.07.2 build576 or later)

  2. Create a draft manuscript using a preferred template in RStudio [This section is in progress-I am currently getting errors!]. Use the appropriate journal template (see here for more info); I will use elsevier for this example.

    1. RStudio –> Terminal (bottom left)

      quarto use template quarto-journals/elsevier

      This will install the extension and create an example qmd file and bibliography that you can use as a starting place for your paper.

    2. In yaml at the top of the document, change the format according to the journal article template you wish to use.

For example:

---
title: "My Awesome Paper"
author: "Me"
format: 
  pdf: default
  elsevier-pdf:
    keep-tex: true

editor: visual
---

As you work on your research, document relevant information in this manuscript (which can later be turned into a report, publication, thesis, etc). If for some reason you drop the project for a few years (ahem!), then you can return to this document to see where you left off.

  1. Introduction: As you review literature, add relevant information to the appropriate paragraph in your introduction, and add citation to References. From the beginning, write in your own works (they need to be clear, but not necessarily well written yet!). If you copy words verbatim, then put in quotes and provide link to reference to be sure you know these are not your own words. The goal is to start putting down relevant information as you come across it– not to write pretty. You can clean up/edit at a later stage.

  2. References: Use Zotero for references (more later!). As you come across literature, put your references in Zotero and cite in your manuscript.

  3. Methods (Draft): For your initial draft manuscript, explicitly input your entire methods (in excruciating detail!) for future reference. Keep track of changes (and reasons for changes) using Issues in Github. Note to Self: We may want to create a separate RMarkdown for super-detailed methods (with version control?), and then cherry pick from this for our final paper methods.

  4. Results: Remember, results are just the facts!

  5. Discussion: If results are the facts, the discussion can provide more information as to the WHY behind your results (and context!). There is (mostly) a strict demarcation between the two sections. Discussion is where the juicy bits go.

  6. Acknowledgements: As your research progresses, be sure to add people, funders, etc to your acknowledgements.

Things to remember as you write:

  • Writing is hard. Do not try to write the perfect words– instead, get the information down. It is much easier to write ideas and then edit them later to make them sound smart than it is to write it all down perfectly the first time.

  • Identify Co-authors: This can be tricky. Everyone approaches this a little differently, but these guidelines can serve as a reasonably standard approach. Discuss early on with your team and as you work with others on your project. If you use guidelines to make your co-author decisions, then this can help alleviate sticky situations related to co-authorship.

  • Be consistent in EVERYTHING, including your approach to topics in the Intro/Methods/Results/Discussion.

  • Do not use subheadings for each paragraph. If you use subheadings, make sure they are consistent across sections (methods, results, and possibly discussion).

  • Follow the rules! (Authors guidelines for your journal)

  • Get Help! Do not wait for the final draft before you share with others. Get help early on to minimize time wasted in re-doing work.

For additional information:

Writing Science: What makes scientific writing hard and how to make it easier (Kathleen Grogan). https://doi.org/10.1002/bes2.1800

Defining the Role of Authors and Contributors (ICMJE). Link here.

A guide to getting published in Ecology and Evolution (BES). Link here.

Video Tutorial: Beautiful reports and presentations with Quarto (RStudio). Link here.