documenting-things

Repo for talk at posit::conf(2023)

First thoughts

Slide one: I'm going to make my case and give tips in 5 minutes from what I have observed and repeat in my own work. Style of Jenny Bryan enabled by tooling like RMarkdown/Quarto + GitHub.Then build out these ideas more with examples from real researchers that we've worked with in gov and academia Slide 2: Walter White meme. "have you ever had this feeling onboardong to a project. Even if it is just you?"

Question to answer: how do you make documenting things maintainable and (dare-I-say) joyful? What if writing documentation was awesome? (Documenting things doesn't have to be painful) Documentation - what am I talking about? Audience. Purpose. Divio.

Governing idea

By documenting things in these 3 ways (voice, modularize, formatting)
You get the effect of more pleasant to write, clear to read, maintained
For the impact of having useful, living documentation, can reuse and fork, become a leader

Outline

2-min intro & signposting

• Hook
• Let me back up, I'm Julie Lowndes. I'm a marine ecologist and I grew up professionally in the R and Open science communities over past 10 years. Shifted my career - Director of Openscapes.
• Talking today about Documenting Things Openly for Future Us.
  • Things - could be code, teaching resources, how to organize files in your group
  • Future Us - mindset beyond you and your computer
  • 5-min lightening talk then stories
  • annotated resources at end; Jenny Bryan 💙

5-min Documenting things doesn't have to be painful

• engaging voice for your audience
  • What do you want to remember. Future Us
  • We not you
  • not dry
• modular design so can be reused/refactored
  • design your docs in a way that can be moved around/refactored (not in a linear way) (importance for maintenance over time)
  • write it down, can be moved later. Helps with incremental writing and not having it loom.
  • this will evolve, like ggplot2
• formatted for readability, sharing, accessibility, and navigation
  • quarto, rmarkdown, google docs
  • as open as possible - shared online (breadcrumbs)

Transition: hopefully now you're interested in hearing some stories of what this looks like and what's possible from it

8-min This is what it looks like & is possible from it (stories)

• Image? like cookbook <> champions <> approach-guide
• NASA teams - Earthdata Cloud Cookbook
  • fits with Carpentries lessons, proj pythia. Contributing section early.
  • maintainance isn't terrible; onboarding new folks
  • Moving to nasa.gov
• Fisheries ecology teams
  • pathways: document event series; nmfs-opensci resource book,
  • NOAA Fisheries open data policy
  • level up in job

2-min Conclusion

no new information in the conclusion!

• revisit hook
• With these 3 things I gave you with the lightening talk, this is possible
  • Doesn’t have to be painful, doesn’t have to be hard, can accomplish great things.

---

High-level Brainstorm

1. voice - write to be useful to you, engaging. What do you want to remember
2. modularize - like we do with code
   1. design your docs in a way that can be moved around/refactored (not in a linear way) (importance for maintenance over time)
   2. this will evolve, like ggplot2, like cookbook <> champions <> approach-guide
3. formatting - readability, accessibility
   1. markdown for code, hyperlink the thing; more helpful than hyperlinking here
   2. alt text - shows when the image doesn't show up. Searchable.
   3. headers for navigation - naming things

Stories:

• Effect
  • FayLab co-creation, onboarding, maintenance; growth & maintain
  • I Fenwick, E Holmes leadership: (pathways: document event series; nmfs-opensci resource book) level up in job

Structure:

• 1 min intro
• 5 min lightening talk (context, flyby, hook)
• 9-10 min stories: effect and impact
• 2 min closing

Resources to Share:

• Stat 545, Happy Git with R, WTF, Naming things
• Divio
• Carpentries Curriculum Developers Handbook - https://cdh.carpentries.org/

Abstract

https://posit.co/blog/keynotes-and-talks-at-posit-conf-2023/

Documenting things: openly for future us

Updated text, Sept 2023

I'll share about documenting things, and how intentional approaches is helping big distributed teams tackle hard challenges and change organizational culture. The goal is to provide concrete tips to help you document things effectively & hear stories of how putting a focus on documentation can be help teams be efficient, productive, and less lonely. I'll give a short lightning talk (inspired by Jenny Bryan's Naming Files) followed by stories from NASA Openscapes & beyond.

Submitted text, Spring 2023

RMarkdown and Quarto are shifting the paradigm for how professionals learn to code, write documentation, and teach others. I'll showcase the style I first experienced by Jenny Bryan (Stat545, Happy Git With R, What They Forgot): narrative and code together, shared openly as a website, that builds trust with learners and provides a resource to consult during and outside of live-teaching. This mode shifts culture in a powerful way, since we can fork this idea, repeat it in our own work. I’ll share examples of how professional researchers are using this style to write open documentation, from technical workflows to community onboarding. I’ll also highlight design elements for writing open documentation, and tips for doing so with Quarto.

Feedback - takeaways

Documentation opens up spaces and makes people feel welcome and part of the team

that documentation is hard, but its's worth it; it can be used to training and orient people to meet them where they are at

To discuss with Sam: CSS

• backgrounds: visually distinguish sections

  • intro, lightning
  • what's possible (repeated)
  • story: nasa cookbook
  • story: nasa 3 years
  • story: noaa+
  • closing (same as intro?)

• fonts: to visually distingish

  • 3 lightning headers from their subsections
  • can we make footer text smaller (like ref-text?)

TO discuss with Stef: story

• closing slide
• NASA place & space

Tips for next 5 days

Practice out loud as much as possible

With a clicker - muscle memory.

When we walk on stage, we are on your time. Wiggle your toes, take a deep breath, start when you're ready. Don't rush. Enjoy it.