From 1b7edd19cd468216b0e1ab331c2903a896356799 Mon Sep 17 00:00:00 2001 From: Julia Stewart Lowndes Date: Fri, 15 Sep 2023 12:58:46 -0700 Subject: [PATCH] update abstract --- README.md | 6 ++++++ index.html | 6 +++--- index.qmd | 8 ++++---- 3 files changed, 13 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 94da223..f1e8831 100644 --- a/README.md +++ b/README.md @@ -97,6 +97,12 @@ 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](https://github.com/jennybc/how-to-name-files#how-to-name-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. diff --git a/index.html b/index.html index 523fee6..ccbc833 100644 --- a/index.html +++ b/index.html @@ -395,9 +395,9 @@

Documenting things doesn’t have to be painful


-

Purpose today: to help you document things effectively & be inspired by teams working together to be more efficient, productive, and less lonely.

+

Purpose today: 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.

@@ -913,7 +913,7 @@

Design: Reuse & complement existing work


Screenshot of Divios Documentation system: a black square with four quadrants labeled Tutorials, How To Guides, Reference, and Explanation

-

Daniele Procida & Divio, The Documentation System

+

Diátaxis & Divio, Documentation System


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

diff --git a/index.qmd b/index.qmd index 9e39ea3..ebb25de 100644 --- a/index.qmd +++ b/index.qmd @@ -18,7 +18,7 @@ format: # highlight-style: a11y # code-line-numbers: false # SPEAKER NOTES -# - Hi! I'm here to share about documenting things and how intentional approaches is helpling teams tackle hard challeges and change culture across organizations like NASA and NOAA communities supporting climate change research and action. +# - 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 --- @@ -83,9 +83,9 @@ Slowing down to speed up.
::: fragment -**Purpose today:** to help you document things effectively & be inspired by teams working together to be more efficient, productive, and less lonely. +**Purpose today:** 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. -- 6-min lightening talk (inspired by [Jenny Bryan's Naming Files](https://github.com/jennybc/how-to-name-files#how-to-name-files) 💙) +- 6-min lightning talk (inspired by [Jenny Bryan's Naming Files](https://github.com/jennybc/how-to-name-files#how-to-name-files) 💙) - 9-min stories from NASA Openscapes & beyond ::: @@ -523,7 +523,7 @@ Don't assume ![](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 -Daniele Procida & Divio, [The Documentation System](https://documentation.divio.com/) +Diátaxis & Divio, [Documentation System](https://diataxis.fr/how-to-use-diataxis/) :::