(AM Session) Foundational Open Science Skills (FOSS) Lesson 4: Intro to Documentation

Date: 2022-10-06
Today Lead Instructor: Michael
Today Helpers: Michele, Jason, Tina, Tyson
Course Website: https://cyverse-learning-materials.github.io/foss
Zoom Link: https://arizona.zoom.us/j/86152278453

Instant Feedback: (please complete before you leave class) Complete Form

Agenda

Warm-up (5 minutes):

Questions & Comments about Data Management?

A bit about the Capstone projects

• not too early to start thinking about what you'd like to do, as individual or as team with others in your class day
• will have a work session before the final presentations (Week 10) where instructors will be available to help

Introduction to Documentation (50 minutes)

Breakout Discussion

• What types of communication do you regularly do? What modes do you use for them?

  • Slack, email, socmedia
  • line betw communication and documentation gets blurry

• What types of documentation do you regularly read? What types do you write? What do you use for this documentation?

  • documentation for R packages (highly variable quality! e.g., RMarkdown)
  • stack overflow threads
  • stack overflow for ARCgis
  • HackMD! (notes)
  • Google docs
  • github wiki (on a repo); can track issues on the repo
  • MKDocs (CyVerse FOSS documentation)
  • ReadtheDocs - powerful, good for highly structured docs; restructured text is a bit complicated

• What kind of organization/structure do you use for documentation?

  • github track issues
  • Michele uses OneNote to document notes/email
  • tina videorecords SOPs of infrequent admin tasks
  • Michael organizes his Chrome bookmarks (nested related folders)
  • Quarto - mix text and code that runs
  • Confluence wiki (Atlassian product)
  • using documentation where/as close to your work lives makes things easier

Communication

https://cyverse-learning-materials.github.io/foss/04_documentation_communication/#communication

Documentation

https://cyverse-learning-materials.github.io/foss/04_documentation_communication/#project-documentation

• documentation framework with 4 quadrants: https://documentation.divio.com/

BioBreak (5 minutes)

Making a GitHub Pages website (do as Homework too)

https://academicpages.github.io/
https://github.com/academicpages/academicpages.github.io

Links shared in class

https://github.com/MCMaurer/R_snippets