Collaborations Workshop 2021 Mini-Workshop: README tips to make your project more approachable

class: inverse, center, middle

# Collaborations Workshop 2021 Mini-Workshop: README tips to make your project more approachable
### Hao Ye
### University of Florida
### (updated: 2022-07-19)

---
You have a project on GitHub.

### .center[🎉 Congrats! 🎉]

How do you get people to engage with it?

* **What** problem does it solve?
* **Who** is the project for?
* **How** does a user install it?
* **Where** does someone go to find more info?

---
# Prerequisites

This lesson assumes you:
* have experience with GitHub projects
* are familiar with writing in markdown

---
# Learning Outcomes

By the end of the workshop, participants will be able to:

* know the different types of technical documentation
* create personas to aid product design
* structure simple READMEs

---
class: inverse, center, middle

# Documentation Types

---
Daniele Procida talks about the **4** kinds of documentation with **different purposes** and requiring **different approaches**.

<img src="procida-title-slide.png" title="A title slide of a dark grey background with the title 'What nobody tells you about documentation' in light blue text at the bottom of the slide. Just above the title is a horizontal light gray line and above that the presenter's name: 'Daniele Procida'." alt="A title slide of a dark grey background with the title 'What nobody tells you about documentation' in light blue text at the bottom of the slide. Just above the title is a horizontal light gray line and above that the presenter's name: 'Daniele Procida'." width="70%" style="display: block; margin: auto;" />
.center[[youtube: PyCon Australia 2017 talk](https://www.youtube.com/watch?v=t4vKPhjcMZg)]

---
class: split-two with-thick-border
.column[
.split-two[
  .row[.content.vmiddle.center[
    ### TUTORIALS
  ]]
  .row[.content.vmiddle.center[
    ### EXPLANATION
  ]]
]]
.column[
.split-two[
  .row[.content.vmiddle.center[
    ### HOW-TO GUIDES
  ]]
  .row[.content.vmiddle.center[
    ### REFERENCE
  ]]
]]

---
class: inverse, center, middle

# User Personas

---
# Definition

**Personas** are descriptions of imaginary users, to help guide the design of your project.

A **good** persona includes:
* background knowledge and experience
* motivations and needs
* concerns and barriers

---
# Example User Persona

.small[River is a PhD student in biology.

River's previous research experience is in a non-computational wet lab. They have taken the standard math courses for biology majors, including stats.

River wants to digitize their data for statistical analyses and to share for other people to use. River is also curious about using other people's data for meta-analyses.

River is using physical logbooks in their current project. River has previously struggled to use Excel in stats class, and is worried after hearing that spreadsheets will alter their data or introduce errors.
]

---
class: center, middle

# User Persona Exercise
## [link](https://ha0ye.github.io/CW21-README-tips/template_persona.html)

---
class: inverse, center, middle

# READMEs

---

# Get ~~students~~ users doing powerful things quickly

.center[*Explanations get in the way of action.*]

Examples of actions:
* Work with real and interesting data
* Create appealing visualizations
* Perform useful analyses

.small[adapted from [David Robinson's blogpost](http://varianceexplained.org/r/teach-tidyverse/)]

---
# Structuring a How-To Guide

* Introduction Section
* How to do {awesome thing}
* Pathway to further usage / engagement
  - full tutorial
  - contributor guide
* License / Acknowledgements

---
# Example README

[The `datapasta` R package](https://github.com/milesmcbain/datapasta/).

---
class: center, middle

# README Exercise
## [link](https://ha0ye.github.io/CW21-README-tips/template_README.html)

---
class: inverse, center, middle

# Takeaways

---
1. Know your users and what they need
2. Get  users doing powerful things quickly
3. Watch out for jargon!