Documenting things: openly for future us
in collaboration with Erin Robinson,
September 19, 2023
posit::conf(2023)
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
all the things
code & analyses
teaching resources
onboarding & community
fieldwork/lab protocols
events
ideas, learning
mindset & habit
ourselves, teams, communities
in the next hour, week, decades
intentional, inclusive
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
In fact, it’s supposed to be helpful.
It does take time and intention. Slowing down to speed up.
Purpose today: to help you document things effectively &
10-min stories - repeatable strategies (from NASA Openscapes & beyond TL;DR )
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
Documenting things
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
It doesn’t matter where at first. Just write it down.
Wiki
Forum/Issues/Discussion
Quarto/Jupyter book
Slide deck
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 Develop the habit of writing things down in this place; copy/paste from email.
Break down documentation as an otherwise big and looming task.
Keyboard shortcuts: Arrow keys + shift + option + command (Mac); + Ctrl + Fn (PC)
Write in a modular way Writing in small bits is less daunting to write & maintain collaboratively.
Modular bits can be networked; not limited to linear flow. Don’t repeat yourself (DRY )!
No true order;
Lowndes & Horst, R for Excel Users
Instead of writing things twice, know where the information is so you can link to it (Don’t repeat yourself (DRY)
You’re writing this for someone. Often, many audiences with different entryways.
Make it engaging, specific. Doesn’t have to be dry or distant.
Write in an inclusive tone 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”
Purpose, Outcomes, Process (POP )
Carpentries Curriculum Developers Handbook (CDH )
eScience SnowEx Hackweek Team-building (slides & website )
“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 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 feature to help!
Amy Steiker & NASA Openscapes Mentors, NASA Earthdata Cloud Clinic
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 Share early to iterate and receive feedback. Open does not always mean public.
Consider permissions & leverage different technologies to leave breadcrumbs.
NOAA Fisheries Open Science, Resource Book
Breadcrumbs. Internal link for NOAA Fisheries. That’s ok. We can still all learn a lot by having as much public.
Leverage defaults and best practices
Allaire et al, Quarto.org
Use text formatting Formatting helps your readers follow along.
Hyperlink the important text, not that this important thing is here .
Distinguish code with fonts; (in Markdown use backticks: `code` )
Alternative text (“alt text”) Use alt text to describe the details and takehome messages in your visuals.
Caption: Knitting text and code
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.
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
What’s possible from this
Putting a focus on documentation has enabled NASA
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
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
Place: Earthdata Cloud Cookbook
Audience: Us first, then specific researchers
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.
Focus on onboarding
Don’t assume
Design: Reuse & complement existing work
Framework - helped NASA Mentors focus on learning & problem oriented documentation.
What’s possible from this
3 places for 3 audiences, designed for onboarding
Place: Project website
Audience: NASA Leadership
Overview:
Approach Guide
Openscapes team
How we work:
What’s possible from this
Putting a focus on documentation has enabled
Invest in both technical & social infrastructure
Documenting things ultimately saves time - fewer emails asking where things are; people feeling less lost and like they belong .
Requires intention & time ; investment in psychological safety & growth mindset.
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
More depth on everything
