collaborate.qmd

---
execute: 
  echo: false
  warning: false
---

# Open science for collaboration {#collaborate}

```{r}
library(fontawesome)
```

## Goals and motivation

This is the second module in our workshop on open science. This module will explore some open science tools to help you and your team become better collaborators and to better engage your science with external partners. We'll introduce some essential elements of collaboration and discuss some readily available tools for doing so.

-   **Goal**: understand methods of collaboration and the pros/cons of various tools
-   **Motivation**: start building the tools for your open science toolbox

## Essential elements of collaboration

We start our deep dive into open science by focusing on collaboration as a fundamental activity that can be enhanced through transparent, efficient, and reproducible tools. Having effective tools to work together is a critical theme of many open science practices. There are many tools in the toolbox and we need to introduce some core concepts before we demonstrate how to implement them in practice.

### Workflow management

How do you organize your work each day? How do you make sure projects are on schedule and pressing deadlines are met? How do you plan for short-term and long-term goals? Do you have a five-year, ten-year, or longer career plan?

Work to achieve goals cannot be accomplished without a systematic approach to organizing tasks. Chances are, we each have our own system that works for us and was probably developed through trial and error. Although everyone has familiar workflows, they are often idiosyncratic and deeply entrenched by habit. That can be in direct conflict with collaboration when we try to mesh internal workflows with those of others.

Does this look familiar?

```{r}
#| out.width: "50%"
#| fig-align: "center"
knitr::include_graphics('img/old_files.png')
```

Although the above comic from [xkcd](https://xkcd.com/){target="_blank"} speaks directly to file management, it hints at a broader problem of personal information management that can seriously complicate working with others. I'm sure we've all struggled to find that one file for that one project from a vague recollection of seeing it a few months ago.

Collaborative work can be facilitated through workflow management that helps you break out of old habits. We'll introduce some specific internet-based tools below to facilitate workflows either for yourself or, better yet, working with others. These can help propel you towards open science.

Here, we introduce the [Kanban](https://en.wikipedia.org/wiki/Kanban_(development)){target="_blank"} approach to workflow management. The idea is simple. Create a task-oriented workflow using a card management system organized by progress. It looks something like this:

```{r}
#| out.width: "60%"
#| fig-align: "center"
knitr::include_graphics('img/kanban.jpg')
```

As shown, this approach can work as a literal, physical board or as one used digitally through a web browser or other software. Every Kanban board has the following elements that allow you to work in a more informed manner:

-   Provides a "big picture" of progress
-   Organizes progress by discrete steps
-   Establishes cards as specific tasks

Many of the open science tools we describe below use this system. It is a generalizable format that works in different settings, whether it be general project management or something more formal like software development.

### Version control

A specific problem for workflow management that can be solved by open science tools is file management. Workflows can be immensely enhanced by tools that use strict guidelines for tracking changes and allowing a complete view of the evolution of a project. This is where version control comes in.

I'm sure many of you have fallen into this trap:

```{r}
#| out.width: "50%"
#| fig-align: "center"
knitr::include_graphics('img/filehell.png')
```

Version control is a way to track the development history of a project. It serves the joint purposes of:

1.  Formally documenting the changes that have been made to code or software
2.  Making sure that the development history is permanent
3.  Providing a system for collaborating across platforms ([with friends!](https://docs.google.com/presentation/d/1M6EfHmZZ6nQvkvZzPHOkSOwj3PpNcd0u291LMMFFOiE/edit#slide=id.gf166433ec7_0_68))

It's more than saving files. Documenting changes with a set of commands that follow strict rules provides a transparent record for yourself and others, and establishing permanency ensures that any of the changes that are made can be vetted and accessed as needed. Think of it as an insurance plan for your project.

If you've ever used Google Docs, you might have noticed a feature that looks a lot like version control. The Google Drive platform is a great way to start working together and a great way to familiarize yourself with the basics of version control.

```{r}
#| out.width: "100%"
#| fig-align: "center"
knitr::include_graphics('img/docsversion.png')
```

For any Google Doc, clicking on the link shown by the arrow will open the Version history pane which shows all of the edits that were made to the document.  You can view any of the edits, who made the edits, view the changes (before/after) in the document, or even restore the document to a previous version.

```{r}
#| out.width: "100%"
#| fig-align: "center"
knitr::include_graphics('img/docshistory.PNG')
```

These are the building blocks of version control as demonstrated with Google Docs:

1. No iterative and ambiguous file naming
1. History of changes assigned to each editor
1. Ability to restore a previous version

Perhaps more importantly, these tools are in the cloud and openly accessible (unlike other cloud-based services). File links (via a URL) also do not change if a file is moved to a different location in the drive.  Overall, the Google platform is an accessible means of improving collaboration (but not without it's [cons](https://tbep-tech.github.io/tbep-os-workshop/collaborate.html#cons-2)).

### Git and GitHub

Although Google products can get you a long way towards better collaboration, they do not use dedicated version control software.  These tools become more important as your projects become more complex - those beyond simple documents or spreadsheets. 

The most widely used software for version control is [Git](https://git-scm.com/){target="_blank"}. Although we do not cover the specifics of this software, it's useful to understand the purpose and what it can do in making your work more open and impactful. Git is integrated with many popular open source development platforms, such as [RStudio](https://support.posit.co/hc/en-us/articles/200532077-Version-Control-with-Git-and-SVN){target="_blank"}.

Many people often confuse Git with [GitHub](https://www.github.com){target="_blank"}. GitHub is an online platform for working collaboratively through Git AND it allows you to be open with your work. We'll provide some examples below of how this can be done. Importantly, you do not need to be an expert in Git to be able to use GitHub. This speaks volumes for how team efficiency can be improved with GitHub through better collaboration.

This recent blog provides a helpful introduction to [Git/GitHub for the casual user](https://masalmon.eu/2023/01/12/git-github-casual/){target="_blank"}. 

```{r}
#| out.width: "25%"
#| fig-align: "center"
knitr::include_graphics('img/Octocat.png')
```

```{r}
#| out.width: "60%"
#| fig-align: "center"
#| fig-cap: "Octocat, the strange and loveable mascot of GitHub."
knitr::include_graphics('img/whatisocto.png')
```

<h4>`r fa('circle-exclamation')` Challenge </h4>

Many institutions block access to Google products or GitHub. See [some ideas](https://tbep-tech.github.io/tbep-os-workshop/implement.html#what-does-it-mean-to-be-open) in our last module to overcome this issue.

<h3>`r fa('chalkboard-user')` Watch and learn</h3>

Workflow management in the real world - using GitHub to collaborate.  Here we present some examples from the Tampa Bay Estuary Program [State of the Bay](https://tbep.org/estuary/state-of-the-bay/){target="_blank"} report and [water quality report card](https://tbep.org/water-quality-report-card/){target="_blank"}. 

<h3>`r fa('chalkboard-user')` Watch and learn</h3>

Now we'll demonstrate how to setup a version control project with RStudio, Git, and GitHub. This example will cover:

1. Creating the project in GitHub
1. Creating a file, adding content, and committing it to the project
1. Setting up issues in GitHub
1. Adding members to the project
1. Creating a Kanban project board to assign tasks 

### Code of Conduct

Every responsible collaborative team begins work by creating a Code of Conduct. This documents a set of community and social standards within which the work can be completed. It ensures all viewpoints are heard and respected and establishes a means by which conflicts can be resolved.

Here's a great example from our friends at [openscapes](https://www.openscapes.org/code-of-conduct/){target="_blank"} and one from the [ROpenSci](https://ropensci.org/code-of-conduct/){target="_blank"} community. Some guidance for creating a code of conduct is also provided in this [blog post](https://ropensci.org/blog/2016/12/21/commcallv12-review-coc/){target="_blank"} from ROpenSci.

The goal of every code of conduct is to ensure an agreed upon set of norms are used by all team members to help create a safe and positive experience.

## Additional tools for collaboration

Below we introduce additional web-based tools that you can use to improve collaboration and openness, including those described above. We present them as a suite of options to consider based on the pros and cons associated with each tool. This is by no means a comprehensive list, but it should get you started towards better collaboration in an open environment.

### Slack

```{r}
#| out.width: "15%"
knitr::include_graphics('img/slack-logo-icon.png')
```

[https://slack.com/](https://slack.com/){target="_blank"}

<h4>`r fa('question')` What</h4>

An online messaging platform for internal communication. Conversations can be organized by topic (via channels) or you can send direct messages to one or more team members. You can have multiple workspaces for different groups.

<h4>`r fa('thumbs-up')` Pros</h4>

Alleviate email overload through quick, informal messaging. Offers a fresh approach to online communication.

<h4>`r fa('thumbs-down')` Cons</h4>

Yet another thing to monitor. Free subscription limits archive of messages. Communication is limited to those in the same workspace.

### Trello

```{r}
#| out.width: "15%"
knitr::include_graphics('img/trello.png')
```

[https://trello.com/](https://trello.com/){target="_blank"}

<h4>`r fa('question')` What</h4>

A Kanban style workflow organization platform. Can be used for personal organization or in teams. Card management allows you to assign due dates, add attachments, make checklists, assign tasks to yourself or team members, and label by themes.

<h4>`r fa('thumbs-up')` Pros</h4>

Easy to use and can upgrade with "power-ups" for integration with other services (e.g., Google). Use across locations (e.g., from home or in the office) is easy because it's based in a web browser.

<h4>`r fa('thumbs-down')` Cons</h4>

Not entirely open because it's only visible to yourself or those you explicitly invite. Free version is limited to only a handful of "power-ups".

### Google Drive

```{r}
#| out.width: "15%"
knitr::include_graphics('img/Google_Drive_logo.png')
```

[https://google.com/drive](https://google.com/drive){target="_blank"}

<h4>`r fa('question')` What</h4>

Cloud-based platform for sharing documents, worksheets, slides, etc. Follows a familiar file-based structure that is common to most operating systems.

<h4>`r fa('thumbs-up')` Pros</h4>

Easy to use and can be a very open space for collaboration. Fairly interoperable with different file formats. Some functionality with version control (i.e., ability to "revert" to previous versions and to view changes).

<h4>`r fa('thumbs-down')` Cons</h4>

Requires a Google account and access can be tricky depending on institution. Even though some versioning is provided, the format can encourage poor file management. Who knows what Google is doing with your data.

### Office 365

```{r}
#| out.width: "25%"
knitr::include_graphics('img/office365.png')
```

[https://www.microsoft.com/en-us/microsoft-365](https://www.microsoft.com/en-us/microsoft-365){target="_blank"}

<h4>`r fa('question')` What</h4>

Cloud-based platform for secure sharing of Microsoft documents, worksheets, slides, etc.

<h4>`r fa('thumbs-up')` Pros</h4>

Easy to use and fully supports Microsoft products. Low barrier of inclusion to others that are already using Microsoft products.

<h4>`r fa('thumbs-down')` Cons</h4>

Requires a Microsoft account and access can be tricky depending on institution. Maintains dependency on expensive Microsoft products that aren't reproducible or interoperable. Very often used in closed workflows.

### GitHub

```{r}
#| out.width: "25%"
knitr::include_graphics('img/Octocat.png')
```

[https://github.com](https://github.com){target="_blank"}

<h4>`r fa('question')` What</h4>

Cloud-based platform for sharing code with Git version control. Supports sharing of most file types, although code and text-based files are the primary use.

<h4>`r fa('thumbs-up')` Pros</h4>

Collaborative and fully transparent work environment for files under version control. Supports workflow management through issue tracking and Kanban style project boards. Links to third-party platforms for archiving and DOI generation (e.g., [Zenodo](https://zenodo.org/){target="_blank"}). Octocat mascot is super cute.

<h4>`r fa('thumbs-down')` Cons</h4>

Learning curve is steep if you want to fully leverage version control. Not a formal data archival service by itself and file sizes are limited.

<h3>`r fa('hat-wizard')` Exercise and discussion</h3>

In small groups, setup a shared workspace using GitHub and create a project management board.  Some real world examples of why you might do this were presented in the earlier [watch and learn](https://tbep-tech.github.io/tbep-os-workshop/collaborate.html#watch-and-learn).

1. Open [GitHub](https://www.github.com){target="_blank"} in a web browser and have one person create a new repository (the big, green "New" button in Repositories). Add each member to the repository after it's created (hint: Settings -> Collaborators)
1. Have that same person create a project board for the repository (Hint: Projects -> New project -> board format)
1. After each person accepts the invitation to the repository (check your email!), each new member create a new file in the repository (Hint: Click "Add file" near the top). Name it something unique, save and commit the changes
1. Assign issues to different members of the repository to do something to the new files (Hint: on the right menu, select "Assignees").  Add the issue to the project board (Hint: on the right menu, select "Projects" and click the new project).
1. Work on the issues until the time is up.  Close each issue as they're completed.