Merge pull request #58 from Openscapes/epa-julie-aug

bigger improvements from EPA feedback

_make_pdf.qmd

@@ -7,7 +7,7 @@ citation_url: https://openscapes.github.io/series
 format:
   pdf:
     toc: true
-    toc-depth: 2
+    toc-depth: 3
     number-sections: true
     number-depth: 1
     output-file: "openscapes-series"
@@ -61,17 +61,19 @@ process_qmd <- function(file, fpath_in = "images/", fpath_out = "images/", level
 
 parts <- list(
   list(title = "Welcome", dir = ".", file = "index.qmd", img_path = "images/", level = 1),
+  list(title = "Program Summary", dir = ".", file = "program-summary.qmd", img_path = "images/", level = 1),
+  list(title = "What to Expect", dir = ".", file = "what-to-expect.qmd", img_path = "images/", level = 1),
+  list(title = "Pathways & Outcomes", dir = ".", file = "pathways.qmd", img_path = "images/", level = 1),  
   list(title = "Core Lessons", dir = "core-lessons", file = "index.qmd", img_path = "images/", level = 1),
   list(title = "Mindset", dir = "core-lessons", file = "mindset.qmd", img_path = "images/", level = 2),
   list(title = "Better Science", dir = "core-lessons", file = "better-science.qmd", img_path = "images/", level = 2),
-  list(title = "GitHub Strategies", dir = "core-lessons/github", file = "index.qmd", img_path = "images/", level = 2),
-  list(title = "GitHub for publishing", dir = "core-lessons/github/", file = "github-pub.qmd", img_path = "images/", level = 3),
-  list(title = "GitHub for project management", dir = "core-lessons/github/", file = "github-issues.qmd", img_path = "images/", level = 3),
   list(title = "Team Culture", dir = "core-lessons", file = "team-culture.qmd", img_path = "images/", level = 2),
   list(title = "Data Strategies", dir = "core-lessons", file = "data-strategies.qmd", img_path = "images/", level = 2),
   list(title = "Coding Strategies", dir = "core-lessons", file = "coding-strategies.qmd", img_path = "images/", level = 2),
   list(title = "Open Communities", dir = "core-lessons", file = "communities.qmd", img_path = "images/", level = 2),
-  list(title = "Pathways", dir = "core-lessons", file = "pathways.qmd", img_path = "images/", level = 2),
+  list(title = "GitHub Strategies", dir = "core-lessons/github", file = "index.qmd", img_path = "images/", level = 2),
+  list(title = "GitHub for publishing", dir = "core-lessons/github/", file = "github-pub.qmd", img_path = "images/", level = 3),
+  list(title = "GitHub for project management", dir = "core-lessons/github/", file = "github-issues.qmd", img_path = "images/", level = 3),
   "# Additional Lessons",
   list(title = "Code of Conduct", dir = "additional-lessons", file = "code-of-conduct.qmd", img_path = "images/", level = 2),
   list(title = "Reporting & SciComm", dir = "additional-lessons", file = "reporting-scicomm.qmd", img_path = "images/", level = 2),

_quarto.yml

@@ -39,6 +39,12 @@ website:
     contents:
       - href: "index.qmd"
         text: Welcome
+      - href: "program-summary.qmd"
+        text: Program Summary
+      - href: "what-to-expect.qmd"
+        text: What to Expect        
+      - href: "core-lessons/pathways.qmd"
+        text: Pathways & Outcomes        
       - section: core-lessons/index.qmd
         contents:        
          - href: "core-lessons/mindset.qmd"
@@ -57,8 +63,6 @@ website:
            text: Coding strategies
          - href: "core-lessons/communities.qmd"
            text: Open communities
-         - href: "core-lessons/pathways.qmd"
-           text: Pathways
       - section: "Additional Lessons"
         contents:
          - href: "additional-lessons/code-of-conduct.qmd"
@@ -88,7 +92,6 @@ website:
         contents:
          - href: "inspiration/resources-that-influence.qmd"
            text: Resources that influence us
-
 
 format:
   html:

additional-lessons/code-of-conduct.qmd

@@ -1,7 +1,5 @@
 ---
 title: Code of Conduct
-aliases: 
-  - ../additional-lessons/code-of-conduct.html
 ---
 
 Please see [Openscapes' Code of Conduct](https://openscapes.org/code-of-conduct) and [slides](https://docs.google.com/presentation/d/11816HbwRCvnr8dFXkk8UqfSy_0O4svEoFFFyHOZ0IBE/) (June 2021) that accompany this lesson.

core-lessons/better-science.qmd

@@ -1,11 +1,11 @@
 ---
-title: "Better science in less time"
+title: "Better science for future us"
 aliases:
   - bsilt.html
   - ../better-science.html    
 ---
 
-Better science is less time is science that is more efficient, reproducible, open, inclusive, and kind. There are growing examples of better science in less time in environmental and Earth science, and beyond, including from the Ocean Health Index team: [Our path to better science in less time using open data science tools](https://www.nature.com/articles/s41559-017-0160) (Lowndes et al. 2017).
+"Better science for future us" is science that is more efficient, reproducible, open, inclusive, and kind. There are growing examples of better science in environmental and Earth science, and beyond, including from the Ocean Health Index team: [Our path to better science in less time using open data science tools](https://www.nature.com/articles/s41559-017-0160) (Lowndes et al. 2017).
 
 ::: {.callout-warning icon="false"}
 ## Slides
@@ -41,15 +41,18 @@ Here we also introduce the [**Pathways concept**](/core-lessons/pathways.qmd) th
 
 ### Create space
 
-The OHI team created space for synchronous collaboration: convenings to learn and teach each other together.
+Creating space means committing to synchronous collaboration convenings to learn and teach each other together.
 
-A critical first part of this was prioritizing time (which included getting buy-in, lobbying, showcasing). Then, this meant that the team could focus time on:
+A critical first part of this was prioritizing time (which included getting buy-in, showcasing). Then, this meant that the team could focus time on:
 
 -   Getting comfortable talking about data/workflows
 -   Building trust (to share imperfect work)
 -   Recognizing that what we invest incrementally will have large dividends in the future
 
-The OHI team started having "Seaside Chats": 1x/week where they discussed filenaming, code review, standard operating procedures and documentation, and much more.
+::: {.callout-note icon="false"}
+# How we did it: OHI Team
+The OHI team started having regular Seaside Chats 1x/week where they discussed filenaming, code review, standard operating procedures and documentation, and much more. We prioritized regular social hours, that we scheduled during work hours so that everyone could participate no matter their other outside-of-work responsibilities.
+:::
 
 ### Create place
 
@@ -61,61 +64,61 @@ Asynchronous collaboration often requires some form of version control so the te
 
 Through creating space and place, teams will find the common workflows, tools, skills that they already have and need to do their work.
 
-For the OHI team, we asked how to make sure everyone can participate as they need to? We introduced new software sparingly, and helped each other learn. This included initial setup as well as follow up and practice. We leveraged existing habits & resources - within and beyond our team. [Open communities](communities.qmd) were a big part of this learning. Through this we were able to distinguish data preparation (tidying) as distinct from our science, and make this actionable by shifting to smaller modular code to combine for different reports/audiences.
-
 **Documentation was a key part of this**. And, writing documentation "for nobody" is very hard, and it's a huge task. We prioritized documentation based on Onboarding and Offboarding: for our future selves first, and then future us.
 
-### What was it really like? Transition to GitHub
-
-Changing behavior/habits takes time, and is messy. Here is part of the story:
+::: {.callout-note icon="false"}
+# How we did it: OHI Team
+The OHI team asked, "how can we make sure everyone can participate as they need to?" Not everyone on the team needed to learn to code, or to use GitHub in the same way. We introduced new software sparingly, and helped each other learn. This included initial setup as well as follow up and practice. We leveraged existing habits & resources - within and beyond our team. [Open communities](communities.qmd) were a big part of this learning. Through this we were able to distinguish data preparation (tidying) as distinct from our science, and make this actionable by shifting to smaller modular code to combine for different reports/audiences.
+:::
 
-![Ocean Health Index (OHI) team's transition of code and shifting communication to GitHub](images/ohi-transition-github.png){fig-align="center" width="80%"}
+### Shifting incrementally
 
-## Ocean Health Index: behind the scenes
+Shifting workflows takes time, particularly because it is most often done while also meeting existing deliverables and deadlines. It requires changing behaviors and habits, which takes time, and is messy, and really depends on the trust built with the team.
 
-Some key points to discuss from [Our path to better science in less time using open data science tools](https://www.nature.com/articles/s41559-017-0160) (Lowndes et al. 2017):
+::: {.callout-note icon="false"}
+# How we did it: OHI Team
 
--   Reproducibility & communication enabled by open tooling
--   Shared practices are useful beyond shared projects
+The OHI shift to using shared Google Docs, R and GitHub was motivated by necessity, reimagined by possibility and community, and done incrementally. It was an investment over years, but the enduring payoff has been huge. 
 
-If you're interested in more overview of the OHI setup, see this 2017 talk (25 mins): [OHI Better science in less time](https://www.youtube.com/watch?v=x4uzVAZvFCA) or this 2021 Plenary at [Better Science for Future Us](https://docs.google.com/presentation/d/1HGw4P095-lblHiGQHXYidHiVysjrPxuojxTxKtE13vk/edit) at the inaugural Society for Open, Reliable, and Transparent Ecology and Evolutionary Biology [SORTEE conference](https://www.sortee.org/events/) (30 minutes) ([video](https://osf.io/47req)).
+Some key points to discuss from [Our path to better science in less time using open data science tools](https://www.nature.com/articles/s41559-017-0160) (Lowndes et al. 2017): reproducibility & communication enabled by open tooling; and shared practices are useful beyond shared projects.
 
-### OHI pathway
+![Ocean Health Index (OHI) team's transition of code and shifting communication to GitHub](images/ohi-transition-github.png){fig-align="center" width="80%"}
 
--   Motivated by necessity
--   Reimagined by possibility and community
--   Done incrementally!
--   Yes: it's an investment.
--   Also yes: huge, enduring payoff for (your) science
+If you're interested in more overview of the OHI setup, see this 2017 talk (25 mins): [OHI Better science in less time](https://www.youtube.com/watch?v=x4uzVAZvFCA) or this 2021 Plenary at [Better Science for Future Us](https://docs.google.com/presentation/d/1HGw4P095-lblHiGQHXYidHiVysjrPxuojxTxKtE13vk/edit) at the inaugural Society for Open, Reliable, and Transparent Ecology and Evolutionary Biology [SORTEE conference](https://www.sortee.org/events/) (30 minutes) ([video](https://osf.io/47req)).
+:::
 
 ### Reproducibility & communication enabled by open tooling
 
 RMarkdown/Quarto to reimagine data analysis and communication. RMarkdown/Quarto combines analyses & figures together, rendered to your reporting output of choice.
 
-An example: <http://ohi-science.org/betterscienceinlesstime/>
+::: {.callout-note icon="false"}
+# How we did it: OHI Team
+
+An example: <http://ohi-science.org/betterscienceinlesstime>
 
--   Website built with R/RMarkdown & Github\
+-   Website built with R/RMarkdown & Github
 -   You can get started too: [1-hour RMarkdown tutorial](https://jules32.github.io/rmarkdown-website-tutorial/); [Quarto website tutorial](https://openscapes.github.io/quarto-website-tutorial/)
+:::
 
 ### Shared workflows not only useful for shared projects
 
+It's about increasing efficiency and reproducibility and open science. But it is also about increasing participation and inclusion. Consider how inclusion and equity show up in your daily practices. How you work and onboard others to your projects is a DEIA issue.
+
+::: {.callout-note icon="false"}
+# How we did it: OHI Team
+
 -   OHI team: we identified as a team & prioritized helping each other
     -   We work on many different projects
     -   Use same workflows, share feedback, can think together across projects
 -   Shared conventions reduce friction & cognitive load
     -   Common ground, easier to talk about, easier to ask for help
     -   You don't need to design everything from scratch
 
-And, critically:
+:::    
 
--   It's about increasing efficiency and reproducibility and open science.
--   But it is also about increasing participation and inclusion.
--   Consider diversity, equity, and inclusion in your daily practices.
--   How you work and onboard others to your projects is a DEI issue.
+## Impact of shifting to open science
 
-## Examples: environmental science
-
-Here are a few examples to showcase what is possible and being done by the community.
+Here are a few examples to showcase what is possible and being done in environmental science.
 
 -   [Regime Shifts in R & Data Science within the BC Public Service Observations from the field](https://stephhazlitt.github.io/regime-shifts/slides#1) - Stephanie Hazlitt, Government of British Columbia, slides from CascadiaRconf keynote
 -   [NMFSReports: Easily write NOAA reports and tech memos in R Markdown](https://github.com/EmilyMarkowitz-NOAA/NMFSReports/blob/main/presentations/2021-06-05NMFSReports-RCascadiaConf.pdf)! - Emily Markowitz, NOAA Alaska Fisheries Science Center, slides from CascadiaRconf talk
@@ -124,6 +127,20 @@ Here are a few examples to showcase what is possible and being done by the commu
     -   [TBEP's Data Management Workflow](https://tbep-tech.github.io/data-management-sop/workflow.html) and open science cake
     -   [Coordinated monitoring of the Piney Point wastewater discharge into Tampa Bay: Data synthesis and reporting](https://www.researchgate.net/publication/373388123_Coordinated_monitoring_of_the_Piney_Point_wastewater_discharge_into_Tampa_Bay_Data_synthesis_and_reporting), 2023. Florida Scientist, 86(2), pp.288-300 - Beck, M.W., Burke, M.C., Raulerson, G.E., Scolaro, S., Sherwood, E.T. and Whalen, J.
 
+::: {.callout-note icon="false"}
+# How we did it: OHI Team
+
+Ocean Health Index has produced annual reports for 12 years (2012-2024) and counting! There are many impacts of this, but at a glance: 
+
+- In 2012, it took 30 people 4 years and several $M to complete the 1st annual OHI report. 
+It would not continued if it costed so much time and $ each time. 
+- In 2024, it takes 3 masters students in 3 months and $200K. 
+
+This is possible because of the incremental investment to make it reproducible, efficient, documented - focus on onboarding. Impacts mean that students and team can focus on new questions, making sense of results, and applications from this, not the assessment itself.
+And, it accelerates the rate at which other teams can get to this cost savings, since OHI is an example that it’s possible, a working open example.  
+:::
+
+
 ## Further resources
 
 ### Not so standard deviation podcast

core-lessons/coding-strategies.qmd

@@ -63,9 +63,12 @@ project (“product”).
 -   Name of your home directory.
 -   R code you ran before lunch.
 
-**Clearly product:** - Raw data. - R code someone needs to run on your
+**Clearly product:** 
+
+- Raw data. 
+- R code someone needs to run on your
 raw data to get your results, including the explicit library() calls to
-load necessary packages. (script, notebook)
+load necessary packages. (script, notebook).
 
 **Ideally, you don’t hardwire anything about your workflow into your
 product.**

core-lessons/communities.qmd

@@ -20,7 +20,7 @@ Open communities play a big role in advancing research, helping research feel le
 
 ------------------------------------------------------------------------
 
-In your work, you're not limited to the people & resources in your physical environment! Open communities are waiting for people like you to come participate in whatever way feels comfortable right now. Awesome people are developing and sharing code and learning resources. They connect through open communities and software (GitHub, forums, Mastodon, Bluesky, TikTok, Slack)
+In your work, you're not limited to the people & resources in your physical environment! Open communities are waiting for people like you to come participate in whatever way feels comfortable right now. Awesome people are developing and sharing code and learning resources. They connect through open communities and software (GitHub, forums, Mastodon, Bluesky, Slack)
 
 We can all learn, reuse, remix, share, and contribute and this means less reinventing, more doing, more fun!
 

core-lessons/github/github-issues.qmd

@@ -43,7 +43,7 @@ While there are many options for project management software out there,
 we use and teach GitHub because it's already managing our code and our
 work, and linked to our collaborators so it offers a streamlined way to
 communicate. (It's also one less account to manage, which is a huge
-bonus in Julie Lowndes' mind).
+bonus!).
 
 One of the reason we talk about Issues in Openscapes is because they are
 an excellent way to develop habits for using GitHub for your analytical
@@ -121,7 +121,7 @@ sometimes Issues are public and sometimes they are private.
 -   In a private repo, only users with permission can create and comment
     on issues, or see them at all
 
-GitHub search is awesome – it will search all of your files and Issues!
+Remeber GitHub's search is awesome – it will search all of your files and also Issues!
 <!---I find this really helpful...--->
 
 ## Issues in the Wild
@@ -130,7 +130,7 @@ Here are some examples of "traditional" and "non-traditional" use of
 issues.
 
 [ggplot2's Issues](https://github.com/tidyverse/ggplot2/issues) is an
-example of what I think is the "traditional" use of Issues, which is in
+example of the "traditional" use of Issues, which is in
 a pretty pure software development context. This is a public repository,
 and all topics are directly related to ggplot2. Issues are largely used
 to report bugs, troubleshoot and sometimes to request features. Note the
@@ -336,9 +336,7 @@ fact, you can have multiple projects within the same repository, so
 different people can have different Projects organized within their
 shared repository, for example.
 
-You have a lot of control over how you will manage your Projects; at
-this point I do not use all the features but have been playing around
-with using them for Openscapes planning:
+You have a lot of control over how you will manage your Projects. Here is one view:
 
 <br>
 
@@ -378,7 +376,8 @@ repository's Settings) will make not only the code and files of that
 repo public, but also all the Issues. Which is fine, but it might add
 considerations in terms of what is discussed in those Issues.
 
-### Ocean Health Index example
+::: {.callout-note icon="false"}
+# How we did it: OHI Team
 
 Here is an example of the Ocean Health Index team’s thought process &
 strategy.
@@ -399,6 +398,7 @@ These two needs led us to create a single private repository named
 especially since our team-lead can engage in these discussions by
 receiving emails about the Issues in their inbox, and can respond
 without having to go to GitHub.com.
+:::
 
 ## Your Turn: Create & comment on issues
 
@@ -407,7 +407,7 @@ Issues. Here is what to do:
 
 -   Go to
     [github.com/openscapes/demo/issues](https://github.com/openscapes/demo/issues)
--   Create an issue, tag people in your breakout group (ask for their
+-   Create an issue, tag colleagues (ask for their
     username)
 -   Browse issues, comment in other issues
 -   Try:
@@ -416,14 +416,14 @@ Issues. Here is what to do:
     -   Adding Issues to a Project (create one if need be)
     -   Closing an Issue
 
-Have fun! And throughout the process, talk to your breakout group, and
+Have fun! And throughout the process, talk to your colleagues, and
 share what you learn.
 
 Here's what your inbox will look like afterwards:
 
 <br>
 
-![](images/issues-inbox-crop.png){fig-align="center" width="80%"}
+![](images/issues-inbox-crop.png){fig-align="center" width="70%"}
 
 <br>