(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

Image Not Showing Possible Reasons
The image file may be corrupted
The server hosting the image is unavailable
The image path is incorrect
The image format is not supported
Learn More →

Agenda

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

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