index.qmd

---
format:
    revealjs:
        colorlinks: true
        theme: ["style.scss"]
        # slide-number: c/t
        height: 900
        width: 1600        
        transition: fade
---

## {#title-slide data-menu-title="Title Slide" background="#53C9DF"}

::: {.custom-title .takeaway}
Documenting things: <br> *openly for future us* 
:::

<br>

::: {.subtitle}
Julia Stewart Lowndes 
:::

in collaboration with Erin Robinson, <br>NASA Openscapes Mentors, &<br> the Openscapes Community

September 19, 2023

posit::conf(2023)



<br>
<br>

::: {.title-footer}
[openscapes.github.io/documenting-things](https://openscapes.github.io/documenting-things/) [(source)](https://github.com/openscapes/documenting-things) [(youtube)](https://www.youtube.com/watch?v=OVM5Ok7W1NQ) 
:::

::: notes
Hi! I'm here to share about documenting things and how intentional approaches is helpling teams tackle hard challeges and change organizational culture. 

My name is Julie Lowndes. I'm a marine ecologist and I grew up professionally in the R and Open science communities over past the 10 years. Documenting things has been a big part of shifting my career I now lead  a program called Openscapes. 

So let's talk about Documenting things: Openly for future us
:::

## {#things-future-us data-menu-title="Things Future Us" background="#53C9DF"}

::: columns
::: {.column width="45%"}
::: {.takeaway-left-shout}
THINGS  
:::

::: {.takeaway-left-state}
**all the things**
 
-   code & analyses
-   teaching resources
-   onboarding & community
-   fieldwork/lab protocols
-   events
- ideas, learning
:::
:::

::: {.column width="45%"}
::: {.takeaway-left-shout}
FUTURE US
:::

::: {.takeaway-left-state}
**mindset & habit**
 
-   ourselves, teams, communities

-   in the next hour, week, decades

-   intentional, inclusive
:::
:::
:::

::: notes
when I say things, I mean all the things. When I say future us, I'm thinking of a mindset beyond you and your computer. So thinking about how what you document now can save hundreds of emails later asking where things are or how to do things.
:::

---

## Documenting things doesn't have to be painful {.takeaway-left-shout-h2 background="#53C9DF"}
::: {.takeaway-left-state}
::: fragment
In fact, it's supposed to be helpful.
:::

<br>

::: fragment
It does take time and intention. Slowing down to speed up. 
:::
:::

<br>

::: fragment
::: {.takeaway-left-state}
**Purpose today:** to help you document things effectively & <br>hear stories of how documentation can be visible and valued — and help teams be efficient, productive, and less lonely. 
:::

<br>

::: {.yellow-bg}
**5-min lightning talk** - practical tips (inspired by [Jenny Bryan's Naming Files](https://github.com/jennybc/how-to-name-files#how-to-name-files) 💙)
:::

<br-smaller>

::: {.white-bg}
**10-min stories** - repeatable strategies (from NASA Openscapes & beyond [TL;DR](https://eartharxiv.org/repository/view/5948/))
:::

:::

::: notes
it's supposed to be helpful

It does take time, and intentionality. 

We're going to talk about practiacl tips in a lighttning talk and then in stories we'll give more about creating that time and visbility for this valuable work. And the TL;DR is in this  editorial about 
<!-- place: tech: google docs, README, Zoom, office, Quarto, GitHub, slot in your calendar -->
<!-- space: people: time, approval from your supervisor, physical , intentional, part of your job, advocating. coworking is the practice of creating space -->
<!-- The hard part about documentation is being intentional, having this be part of your job. Making space is the hard part -->
:::

## **Documenting things** {background="#FFF6E1" .takeaway}

<br>

::: doc-things-text
{{< fa angle-right >}} Have a place

{{< fa angle-right >}} Have an audience in mind

{{< fa angle-right >}} Design for readability & accessibility
:::


::: notes
- my opinionated take on documenting things”

-   I'm also here to say documenting things doesn't have to be painful to write and boring to read.
-   I have 3 pieces of advice:
-   the plan for today
:::

## {{< fa angle-right >}} Have a place {background="#FFF6E1"}

It doesn't matter where at first. Just write it down. 

<br>

::: columns
::: {.column width="33%"}
<br>

**Google Doc**

<br>

<br>

**Notion**
:::

::: {.column width="33%"}
<br>

**Wiki**

<br>

<br>

**Forum/Issues/Discussion**
:::

::: {.column width="33%"}
<br>

**Quarto/Jupyter book**

<br>

<br>

**Slide deck**
:::
:::

::: notes
This can be whatever software you have transition: what's important about having a place is that it helps you write as you go -
:::

## *Write as you go* {background="#FFF6E1"}

Develop the habit of writing things down in this place; copy/paste from email.

Break down documentation as an otherwise big and looming task.

<br>

**Keyboard shortcuts: Arrow keys + shift** + option + command (Mac); + Ctrl + Fn (PC)





::: borderbox
![](images/keyboard-shortcuts-kinder-science.png){fig-alt="Screenshot of text in a Google Doc that is highlighted half-way, with the last line of highlighing ending at the end of one sentence." fig-align="center" width="55%"}
:::

::: ref-text
Lowndes et al, [Shifting institutional culture to develop climate solutions with Open Science](https://eartharxiv.org/repository/view/5948/)
:::

::: notes

:::

## *Write in a modular way* {background="#FFF6E1"}

Writing in small bits is less daunting to write & maintain collaboratively.

::: columns
::: {.column width="50%"}
<br>

::: borderbox
![](images/modular-github-annotated.png){fig-alt="Screenshot of an e-book left navigation bar for R, RStudio, and RMarkdown, with subsections Summary, RStudio Orientation, Intro to RMarkdown, R code in the Console, R functions, Help pages, Commenting" fig-align="center" width="100%"}
:::

::: center-text
Modular bits can be networked; not limited to linear flow. 
Don't repeat yourself ([DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself))!
:::
:::

::: {.column width="50%"}
::: borderbox
![](images/modular-r-for-excel.png){fig-alt="Screenshot of an e-book left navigation bar for R, RStudio, and RMarkdown, with subsections Summary, RStudio Orientation, Intro to RMarkdown, R code in the Console, R functions, Help pages, Commenting" fig-align="center" width="40%"}
:::

::: center-text
No true order; <br>you'll move things around.
:::

:::
:::

::: ref-text
Lowndes & Horst, [R for Excel Users](https://rstudio-conf-2020.github.io/r-for-excel)
:::

::: notes
Instead of writing things twice, know where the information is so you can link to it (Don't repeat yourself (DRY)
:::

## {{< fa angle-right >}} Have an audience in mind {background="#FFF6E1"}

You're writing this for someone. Often, many audiences with different entryways. 

Make it engaging, specific. Doesn't have to be dry or distant. 
 
::: borderbox
![](images/happy-git-with-r.png){fig-alt="Screenshot of Jenny Bryan's Happy Git With R book that has an image from the music video Whip that says Watch me Diff, Watch me Rebase" fig-align="center" width="55%"}
:::

::: ref-text
Bryan, [Happy Git with R](https://happygitwithr.com)
:::

::: notes
Picture talking to them
:::


## *Write in an inclusive tone* {background="#FFF6E1"}

We're in this together: Your readers are intelligent & here to learn from you.

Consider your goals and style that welcome readers; e.g. avoid words that trivialize

> Avoid: "simply clone the repo"

<br>

::: {.medium-body-text .blue-underline}
Thoughtful resources
:::

-   Purpose, Outcomes, Process ([POP](https://suzannehawkes.com/2010/04/09/pop-everything/))
-   Carpentries Curriculum Developers Handbook ([CDH](https://cdh.carpentries.org/))
-   eScience SnowEx Hackweek Team-building ([slides](https://docs.google.com/presentation/d/1qJDpFdS42kF5pcrbmxm1xFWzNoNamVrnMFelwAOh73Q/edit#slide=id.gddb97543ad_3_13) & [website](https://snowex-hackweek.github.io/website/))

<br>



::: notes

"simply clone the repo"

Write as if these different audiences are all in the room with you. directed toward different audiences


:::

## *Narrate code in small chunks* {background="#FFF6E1"}

Write short narrations for your code as you'd say it out loud.
Match this with your purpose; it's especially important for teaching.

Quarto now has a new [code annotation](https://quarto.org/docs/authoring/code-annotation.html) feature to help!

<br>

::: borderbox
![](images/cloud-clinic-ex.png)
:::

::: ref-text
Amy Steiker & NASA Openscapes Mentors, [NASA Earthdata Cloud Clinic](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/examples/Earthdata-cloud-clinic.html)
:::

<br>


::: notes
When we write tutorials with code, we write them as if we're teaching them outloud. What you would say is included. And we design the code in chunks for learners.


:::

## *Share early* {background="#FFF6E1"}
Share early to iterate and receive feedback. Open does not always mean public. 

Consider permissions & leverage different technologies to leave breadcrumbs.

<br>

::: borderbox
![](images/nmfs-opensci-508-breadcrumb.png){fig-alt="Screenshot of NOAA Fisheries Open Science Resource Book on the page with 508 Compliance. A red arrow points to blue text that says Recording of R UG Meeting and in red text says Internal link" fig-align="center" width="65%"}
:::

::: ref-text
NOAA Fisheries Open Science, [Resource Book](https://nmfs-opensci.github.io/ResourceBook/content/508_compliance.html)
:::

::: notes
Breadcrumbs. Internal link for NOAA Fisheries. That's ok. We can still all learn a lot by having as much public.
:::


## {{< fa angle-right >}} Design for readability & accessibility {background="#FFF6E1"}
Leverage defaults and best practices 

::: borderbox
![](images/format-quarto.png){fig-alt="Screenshot of the Quarto homepage, which has a nice navigation bar at the top, and stylized text that draws your eye that says Welcome to Quarto and has bullet points describing what it can do with Jupyter, VS Code, RStudio, Websites, Articles, Presentations, Books, and Knowledge Repo icons"  fig-align="center" width="65%"}
:::

::: ref-text
Allaire et al, [Quarto.org](https://quarto.org)
:::

::: notes

:::

## *Use section headers* {background="#FFF6E1"}

Section headers are important for screen readers to describe sections and flow.

You can anchor directly to them to share an anchored URL.

[Naming things](https://github.com/jennybc/how-to-name-files#how-to-name-files) 💙 is key here - "embrace the slug"

::: columns
::: {.column width="50%"}
::: borderbox
![](images/anchor-quarto-annotated.png){fig-alt="Screenshot of Quarto page with a Header anchored, indicated with a red circle and red arrow pointing to the url bar with text that says Clicking anchors URL" width="100%"}
:::

::: ref-text
Fay Lab, [The FayLab Manual](https://thefaylab.github.io/lab-manual/)
:::
:::

::: {.column width="50%"}
::: borderbox
![](images/anchor-gdoc-bookmark-annotated.png){fig-alt="Screenshot of Google Doc with a Bookmark inserted with a red arrow pointing from the Insert nav bar item that says Insert > Bookmark" width="95%"}
:::
::: ref-text
Clatterbuck, Fenwick et al, [3 approaches for the year of open science](https://openscapes.org/blog/2023-03-16-esip-winter-2023/).
:::

:::
:::

::: notes
Helps with accessibility since screen readers treat headers a specific way.
 
These are examples from Google Doc where you can insert a bookmark and Quarto where you can anchor in Markdown.

Maybe: Be Consistent - Not "example" and then 2nd example has a diff name. Indenting.
:::

## *Use text formatting* {background="#FFF6E1"}

Formatting helps your readers follow along. 

<br>

Hyperlink the important text, not that this important thing is [here](https://doi.org/10.2737/RDS-2020-0001).

Distinguish `code` with fonts; (in Markdown use backticks: \`code\` )

::: borderbox
![](images/format-fonts-links.png){fig-alt="Screenshot of a blog post where the hyperlinked text says Fire and Tree Mortality Database and the words tidymodels and geomtextpath are formatted for code" fig-align="center" width="80%"}
:::

::: ref-text
Horst, [Exploring tree outcomes following fires](https://allisonhorst.github.io/posts/2022-03-10-tree-mortality-fires/).
:::



## *Alternative text ("alt text")* {background="#FFF6E1"}
Use alt text to describe the details and takehome messages in your visuals.

![](images/horst-hill-knitting-hedgehogs.png){fig-alt="A round hedgehog knitting a yellow sock. A rabbit with a teal beanie and wearing one yellow sock watches in anticipation. A shelf to the left of them contains yarn in a tote labeled TEXT, and knitting patterns in a tote labeled CODE." fig-align="center" width="80%"}

::: centered
*Caption: Knitting text and code*
:::

<br>

**Alt text**:  A round hedgehog knitting a yellow sock. A rabbit with a teal beanie and wearing one yellow sock watches in anticipation. A shelf to the left of them contains yarn in a tote labeled TEXT, and knitting patterns in a tote labeled CODE.

<br>

::: ref-text
Horst & Hill, [The Hedgehog Series](https://allisonhorst.com/horst-hill-collaborations)
:::


::: notes
note alt text should not just repeat the caption (if you have one) it should be descriptive - paint the picture of whatever you’re talking about so someone with a screen reader can listen to the alt text and get the same details and take home messages as someone who can look at the image
:::

## **Documenting things** {background="#FFF6E1" .takeaway}

<br>

::: doc-things-text
{{< fa angle-right >}} Have a place

{{< fa angle-right >}} Have an audience in mind

{{< fa angle-right >}} Design for readability & accessibility
:::

## What's possible from this {background="#53C9DF" .centered .center}

::: notes
:::

## Putting a focus on documentation has enabled NASA<br>to collaborate across divisions and support users transitioning to Earthdata Cloud {.centered .center}

::: notes
So what are we talking about here
:::

##  {#nasa-earth-fleet .center data-menu-title="NASA Earth Fleet" background-image="images/nasa-earth-fleet.png" background-size="contain" background-color="#000000"}

::: notes
let me remind you that NASA collects an enormous amount of data about our Earth from satellites that is freely available. 
ccessing data in the cloud vs downloading is a huge shift in the workflows and habits researchers/users have developed over careers
In order to support this shift, there is a lot of documentation and teaching resources that we need
:::


## Teaching NASA Earthdata Cloud {background-image="images/nasa-openscapes-logos-background.png" background-size="contain"}
### ...by learning as a community

::: columns
::: {.column width="65%"}
![](images/2021-Cloud-Hackathon-GroupPhotoWave.png){fig-alt="Screenshot of a Zoom meeting with 30 smiling faces" width="100%"}
:::

::: {.column width="35%"}
### NASA Openscapes

- A mentor group across NASA Earth science data centers (DAACs)
- Co-creating and teaching common tutorials alongside researchers as we migrate analytical workflows to the Cloud 

:::
:::


::: ref-text
Steiker et al, [Working with NASA Earthdata in the Cloud](https://docs.google.com/presentation/d/e/2PACX-1vSXgRRZpK9zDcq8Wxf9804GxamHDL69BkxEuDXaVHjexLD4q3sIvv61HLZZJRzCcEoHw-VBBH71lGJv/pub?start=false&loop=false&delayms=3000)

See also: Çetinkaya-Rundel & Lowndes, [Hello Quarto: share • collaborate • teach • reimagine](https://openscapes.org/blog/2022-08-10-quarto-keynote/)
:::

## Place: Earthdata Cloud Cookbook

::: borderbox
![](images/cookbook.png){fig-alt="Screenshot of an e-book made with Quarto for the NASA Cloud Cookbook" fig-align="center" width="70%"}
:::



::: ref-text
NASA Openscapes Mentors, [NASA Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook)
:::

::: notes
Google Drive • GitHub • Quarto • JupyterHub • Zoom • Slack
:::


## Audience: Us first, then specific researchers

![](images/nasa-openscapes-shell.png){fig-alt="Diagram of a colorful shell-spiral shape with NASA Openscapes Mentors community values as a small image up top, then Data Center Staff, then End Users, then Open Science Community" fig-align="center"}

::: ref-text
Steiker et al, [Working with NASA Earthdata in the Cloud](https://docs.google.com/presentation/d/e/2PACX-1vSXgRRZpK9zDcq8Wxf9804GxamHDL69BkxEuDXaVHjexLD4q3sIvv61HLZZJRzCcEoHw-VBBH71lGJv/pub?start=false&loop=false&delayms=3000)
:::

::: notes
us as we onboard = as we start. crumb trail as we learn. 
as we figure things out, we make a crumb trail no matter how small it is

-   Contributing section was early addition; how to access our cloud infrastructure

:::

## Design: Meet people where they are 
We don't assume experience; we all can learn and teach. 

Collaborating across workflows: `.ipynb`, `.Rmd`; VSCode, Jupyter, RStudio, MATLAB.

::: borderbox
![](images/cookbook-onboarding-annotated.png){fig-alt="Screenshot of a quarto e-book called NASA Earthdata Cloud Cookbook with a red box around the left navigation bar section that says Contributing. The main page we see says Onboarding Mentors with subsections like Welcome to the mentor community! and Mentor schedule, tooling checklist" fig-align="center" width="60%"}
:::

::: ref-text
NASA Openscapes Community, [NASA Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/contributing/onboarding)
:::

::: notes
Focus on onboarding

Don't assume
:::

## Design: Reuse & complement existing work

::: columns
::: {.column width="50%"}

<br>
![](images/divio.png){fig-alt="Screenshot of Divios Documentation system: a black square with four quadrants labeled Tutorials, How To Guides, Reference, and Explanation" fig-align="center"}

::: ref-text
Diátaxis & Divio, [Documentation System](https://diataxis.fr/how-to-use-diataxis/)
:::

<br>

**Framework** - helped NASA Mentors focus on learning & problem oriented documentation.
:::

::: {.column width="50%"}
<br>

![](images/open-communities.png){fig-alt="Screenshot of 20 logos from different open communities including Transfor to Open Science, Ladies of Landsat, Posit, rOpenSci, and The Turing Way" fig-align="center" width="82%"}


::: ref-text
Bri Lind at the NASA Hyperwall, [Getting to Know Open Science](https://docs.google.com/presentation/d/1uMfh0ssHGDuJ9q8pcRk8-qIerkywE4X-E_KP4CiptKc/edit#slide=id.g23d8f62188b_2_96)
:::

<br>

**Open community** - helped NASA Mentors learn, scope, co-develop, and share.

:::
:::

::: notes
Mentors found it really helpful to have a framework for thinking of this documentation.
:::

##  What's possible from this {background="#53C9DF" .centered .center}


::: notes
from a documentation perspective
:::


## Putting a focus on documentation has enabled <br>the NASA Openscapes community<br>to grow through intentional onboarding<br>over 3 years {background="#d2e3f3" .centered .center}

::: notes
Maintainance isn't terrible; onboarding new folks & increasing user-contributors

Communities don't grow on their own. We've been explicit about onboarding. 
:::



## 3 places for 3 audiences, designed for onboarding {background="#d2e3f3"} 

<br>

::: columns
::: {.column width="33%"}
**Place: [Project website](https://nasa-openscapes.github.io)** 

Audience: NASA Leadership

::: borderbox
[![](images/nasa-openscapes-web-onboard.png){fig-alt="Screenshot of the project website for NASA Openscapes, with a blue navigation bar across the top and NASA and Openscapes logos in the center"}](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/)
:::

Overview: <br>invite participation, <br>info lives outside email

:::

::: {.column width="33%"}
::: fragment
**[Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/)**

NASA Mentors

::: borderbox
[![](images/cookbook-onboarding.png){fig-alt="Screenshot of an e-book made with Quarto for the NASA Cloud Cookbook"}](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/)
:::

Welcome:<br> access comms & tech,<br> contribute, code review
:::
:::
:::

::: {.column width="33%"}
::: fragment
**[Approach Guide](https://openscapes.github.io/approach-guide)**

Openscapes team

<br>

::: borderbox
![](images/approach-guide-onboard-mentors.png){fig-alt="Screenshot of a Quarto site that is a guide of the Openscapes Approach"}
:::

How we work: <br>purpose, facilitation, <br> checklists & timelines

:::
:::

::: notes
:::

##  What's possible from this {background="#53C9DF".centered .center}

## Putting a focus on documentation has enabled<br>NOAA Fisheries, Cal Water Boards, and others<br> to reuse this approach {background="#FAE3E3" .centered .center}
 
<br>

::: notes
and everything we've done here we're applying to NOAA Fis" other huge impact audiences
:::

## Invest in both technical & social infrastructure {background="#FAE3E3"}

::: columns
::: {.column width="40%"}
**Documenting things ultimately saves time** - fewer emails asking where things are; **people feeling less lost and like they belong**.

<br>

**Requires intention & time**; investment in **psychological safety & growth mindset.**

<br>

{{< fa angle-right >}} Have a place

{{< fa angle-right >}} Have an audience in mind

{{< fa angle-right >}} Design for readability & accessibility


:::

::: {.column width="55%"}

![](images/rios-kim-tomato-plant-kinder-science.png){fig-alt="a digital crayon drawing of a tomato plant in the middle and a colorful circle around it connecting different concepts clockwise, starting at the roots. The roots says Culture, the watering can and toolbox says Technical Infrastructure, the sun says Values, the leaves say Social Infrastructure, and the final basket of tomatoes says Relevant, rigourous, insightful science" width="85%"}
:::
:::

::: ref-text
Lowndes et al, [Shifting institutional culture to develop climate solutions with Open Science](https://eartharxiv.org/repository/view/5948/)
:::

::: notes
It starts with holding intentional, respectful conversations and tapping into the knowledge base of our workplaces, and reusing what works in new places.

- Learning and teaching together is empowering
:::


## Thank you

Openscapes team & community

Open source/science community far and wide, including CSS architect Sam Csik

This work was funded in part by NASA Award #20-TWSC20-2-0003

<br>


### More depth on everything

- [openscapes.org](https://openscapes.org)
- [nasa-openscapes.github.io](https://nasa-openscapes.github.io)
- [nmfs-openscapes.github.io](https://nmfs-openscapes.github.io)
- [cawaterboarddatacenter.github.io/swrcb-openscapes](https://cawaterboarddatacenter.github.io/swrcb-openscapes/)
- [openscapes.github.io/pathways-to-open-science](https://openscapes.github.io/pathways-to-open-science)


::: {.title-footer}
[openscapes.github.io/documenting-things](https://openscapes.github.io/documenting-things/) [(source)](https://github.com/openscapes/documenting-things)
:::