first full draft; need to add intro info on what is a readme

UCSB-MEDS · Aug 21, 2024 · 4c7f5d5 · 4c7f5d5
1 parent ce47e90
commit 4c7f5d5
Show file tree

Hide file tree

Showing 9 changed files with 240 additions and 133 deletions.
diff --git a/images/.DS_Store b/images/.DS_Store
diff --git a/images/lter-org.png b/images/lter-org.png
diff --git a/images/ncar.png b/images/ncar.png
diff --git a/index.html b/index.html
diff --git a/index.qmd b/index.qmd
@@ -1,5 +1,6 @@
 ---
 title: "MEDS README Guidelines"
+subtitle: "When and where to include a README, and what to talk about when you do"
 author: 
   - name: Sam Csik
     url: https://samanthacsik.github.io/
@@ -23,103 +24,10 @@ format:
     smooth-scroll: true
 ---
 
-## What is a README?
+{{< include /sections/README-definition.qmd >}}
 
+{{< include /sections/repo-READMEs.qmd >}}
 
-## Repository-level READMEs
-
-You should always include a [README](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) in the root directory of your GitHub repositories. A README is typically the first item that visitors will see when they arrive at your repository. This makes them the perfect place to tell people what your project is, why it’s useful, and how to get started using it. What you include in a given README will look different depending on the project, but here are some guidelines for getting started:
-
-### Things you should *always* include in your GitHub repository READMEs: {#always-include}
-
-::: {.callout-important}
-These core elements are required for *all* MEDS-related homework assignments and projects.
-:::
-
-1. **A short, but descriptive title** 
-    - A README’s title is set to the repository name by default - change this!
-2. **A brief explanation of the repository’s purpose**
-    - Paragraphs or a bulleted list are both acceptable options
-    - You may include an image or logo that represents the project
-3. **A concise description of what’s housed in the repository**
-    - This includes information about the repository structure or file organization
-4. **Details regarding data access**
-   - Any necessary information on where data lives (e.g. is it housed in the repo, on a server, in a library/package etc.) and how to access it in order to run the code
-5. **A list of authors or current contributors (for collaborative work)**
-    - Consider hyperlinking collaborators' GitHub profiles or other professional profile
-6. **References** 
-    - In an appropriate, consistent format, including links.
-    - Don’t forget to add references for data sets too.
-
-### Things you should consider including, but may vary depending on the goals and complexity of the project: {#consider-including}
-
-1. **How to install or where to start**
-    - Does your repository contain software that users will need to download or install? Do users access your software via a web browser? Do they need to install any dependencies? Do users need to clone your repository? etc.
-2. **A quick demo**
-    - Related to #1, above. It’s important to keep this concise! You may include images. Any long-form instructional documentation is best moved to the repository's wiki
-3. **What do do if a bug is spotted**
-    - Make mention of GitHub issues and what information a user should include in an issue
-4. **Contributing**
-    - Do you welcome contributions from others? If so, its important to explain how one might contribute (e.g. fork & pull request, open an issue, both?)
-5. **License**
-    - Important for allowing others to reuse your work (which is copyrighted, by default; [read about what it means when no license is available](https://choosealicense.com/no-permission/))
-    - What license you choose depends on what type of work you are trying to license. There are different licenses used for code/software, content, and data. Some helpful resources for getting started: 
-        a. *Licensing code / software:* check out this page,[ Choose an open source license](https://choosealicense.com/), by GitHub. A couple popular options for software include [MIT License](https://choosealicense.com/licenses/mit/) and [GNU GPLv3](https://choosealicense.com/licenses/gpl-3.0/)
-        b. *Licensing content (i.e. non-software):* check out this page, [About CC Licenses](https://creativecommons.org/share-your-work/cclicenses/), by Creative Commons. A few good CC options for non-software content include [CC BY](https://creativecommons.org/licenses/by/4.0/?ref=chooser-v1), [CC BY-SA](https://creativecommons.org/licenses/by-sa/4.0/), and [CC BY-NC](https://creativecommons.org/licenses/by-nc/4.0/).
-        c. *Licensing data:* You’ll chat more about this in [EDS 213 (Databases and Data Management)](https://bren.ucsb.edu/courses/eds-213)!
-6. **Acknowledgements**
-    - Provide reference to any other individuals or sources that supported the development of the repository. For example, did you fork an existing repository? Did the work have any funding sources? Were there individuals you consulted with or were inspired by?
-
-### Example GitHub repository READMEs: {#example-repo-readmes}
-
-Each project is different and so is its README! As you browse through different repositories you will see that not all of them have the same sections. However, they all offer a clear starting point for a newcomer to understand what the project is about. Here are some GitHub repositories with READMEs we like:
-
-- [strava-dashboard](https://github.com/samanthacsik/strava-dashboard), by Samantha Csik - code for a Shiny dashboard
-- [EDS-240-data-viz](https://github.com/samanthacsik/EDS-240-data-viz), by Samantha Csik - code for a course website
-- [thomas-fire](https://github.com/annaramji/thomas-fire), by Anna Ramji - a MEDS student project
-- [xarray](https://github.com/pydata/xarray) - a Python package for working with multidimensional arrays and datasets
-- [palmerpenguins](https://github.com/allisonhorst/palmerpenguins/) - an R package that contains teaching data
-- [metajam](https://github.com/NCEAS/metajam) - an R package for downloading and reading in metadata from repositories in the DataONE network
-- [awesome-readme](https://github.com/matiassingers/awesome-readme), by Matias Singers - a curated list of awesome READMEs
-
-## Organization-level READMEs
-
-You have the option to add both public (visible to anyone) and private (visible only to organization members) profile READMEs to separately serve each of those communities. The content you choose to include in an organization profile README is quite flexible, but it's often valuable to add the purpose of the organization, any high-level summary information, and links to important websites / external resources / specific repositories within the organization. Alternatively (or in addition to), you can update your organization's profile information, including a title and description, as well as relevant links. For example, see [NCAR's GitHub organization](https://github.com/NCAR):
-
-```{r}
-#| eval: true
-#| echo: false
-#| fig-align: "center"
-#| out-width: "100%"
-knitr::include_graphics("images/ncar.png")
-```
-
-In [EDS 411 (Capstone Project)](https://bren.ucsb.edu/courses/eds-411b), you’ll create a GitHub organization to house all your Capstone-related repositories and code. You’ll also be required to include specific information in your organization’s README (you’ll talk much more about the [required checklist](https://docs.google.com/document/d/10d9-h8UBC1JwZ08MdxI-WJhxfc7DnUolXjgBV1N-pJA/edit) in EDS 411!). In the meantime, check out a couple great examples of MEDS Capstone organizations, along with a few non-MEDS organizations, below.
-
-### Example GitHub organizations with added profile information:
-
-- [UCSB MEDS](https://github.com/UCSB-MEDS), by the Master of Environmental Data Science program (a place where MEDS admin organize teaching materials and other related content)
-- [The Nature Conservancy](https://github.com/thenatureconservancy), by TNC (scripts and apps from TNC scientists and geologists)
-- [LTER](https://github.com/lter), by the Long Term Ecological Research Network (a home for LTER projects and code)
-
-### Example (public) GitHub organization READMEs:
-
-- [Outdoor Equity](https://github.com/outdoor-equity), by Halina Do-Linh & Clarissa Boyajian (MEDS 2022 Capstone project) 
-- [CASAschools](https://github.com/CASAschools), by Liane Chen, Charlie Curtin, Kristina Glass & Hazel Vaquero (MEDS 2024 Capstone project)
-- [NMFS Open Science](https://github.com/nmfs-opensci), by the National Marine Fisheries Service (contains work which supports open science and open data literacy across NOAA fisheries)
-- [NASA Goddard Institute for Space Studies](https://github.com/NASA-GISS), by NASA (laboratory in the Earth Sciences Division of NASA’s Goddard Space Flight Center)
-- [GitHub](https://github.com/github), by GitHub (yes, GitHub is built on GitHub!)
-
-## Wikis
-
-While READMEs are used to provide a quick overview of what your project can do, wikis are used to provide additional documentation. From [GitHub Docs](https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis):
-
->“You can use your repository's wiki to share long-form content about your project, such as how to use it, how you designed it, or its core principles”
-
-A great way to streamline a repository's README is to move any documentation-style information to a wiki, and then link to the appropriate wiki page from your README. Each wiki page should focus on a single topic.
-
-### Example GitHub repository wikis: 
-- [Openscapes website wiki](https://github.com/Openscapes/website-new/wiki), by Openscapes (a user-guide of sorts; notes and conventions for Openscapes website maintainers and contributors) 
-- [NCEAS Roundtable (August 2023) workshop materials wiki](https://github.com/samanthacsik/cute-cats-dogs/wiki), by Samantha Csik (setup instructions for workshop participants)
-- [`{xaringan}` wiki](https://github.com/yihui/xaringan/wiki), by Yihui Xie (includes tips and further customizations that aren’t covered in the official R package documentation)
+{{< include /sections/org-READMEs.qmd >}}
 
+{{< include /sections/wikis.qmd >}}
diff --git a/sections/README-definition.qmd b/sections/README-definition.qmd
@@ -0,0 +1,24 @@
+---
+format: 
+  html:
+    theme: meds-website-styles.scss
+    mainfont: Nunito
+    toc: true
+    toc-location: left
+    toc-depth: 2
+    smooth-scroll: true
+---
+
+## What is a README?
+
+<!-- A README is a file... -->
+
+<!-- ::: {.callout-note} -->
+<!-- ## Where did READMEs come from? -->
+<!-- No one knows exactly where READMEs originated,  -->
+<!-- ::: -->
+
+<!-- READMEs are not just a "GitHub thing" (though that's primarily where you'll be interacting with them). -->
+
+<!-- While you'll commonly come across content making reference to the importance of READMEs in accompanying package / module developement on GitHub, they are incredibly important documents to include with *all* repositories. -->
+
diff --git a/sections/org-READMEs.qmd b/sections/org-READMEs.qmd
@@ -0,0 +1,41 @@
+---
+format: 
+  html:
+    theme: meds-website-styles.scss
+    mainfont: Nunito
+    toc: true
+    toc-location: left
+    toc-depth: 2
+    smooth-scroll: true
+---
+
+## Organization-level READMEs
+
+**You have the option to add both public (visible to anyone) and private (visible only to organization members) profile READMEs to separately serve each of those communities.** The content you choose to include in an organization profile README is quite flexible, but it's often valuable to add the purpose of the organization, any high-level summary information, and links to important websites / external resources / specific repositories within the organization. **Alternatively (or in addition to), you can update your organization's profile information, including a title and description, as well as relevant links -- these will appear across the top of your organization's landing page.** For example, see [LTER's GitHub organization](https://github.com/lter), which includes both updated profile information *and* a public README:
+
+```{r}
+#| eval: true
+#| echo: false
+#| fig-align: "center"
+#| out-width: "100%"
+knitr::include_graphics("images/lter-org.png")
+```
+
+::: {.callout-note}
+## You'll be asked to create an organization-level READMEs for your Capstone work
+In [EDS 411 (Capstone Project)](https://bren.ucsb.edu/courses/eds-411b), you'll create a GitHub organization to house all your Capstone-related repositories and code. You'll also be required to include specific information in your organization's README (you'll talk much more about the [required checklist](https://docs.google.com/document/d/10d9-h8UBC1JwZ08MdxI-WJhxfc7DnUolXjgBV1N-pJA/edit) in EDS 411). In the meantime, check out a few examples GitHub organizations and their associated README information.
+:::
+
+### Example GitHub organizations with added profile information:
+
+- **[UCSB MEDS](https://github.com/UCSB-MEDS)**, by the Master of Environmental Data Science program (a place where MEDS admin organize teaching materials and other related content)
+- **[The Nature Conservancy](https://github.com/thenatureconservancy)**, by TNC (scripts and apps from TNC scientists and geologists)
+- **[NCAR](https://github.com/NCAR)**, by the NSF National Center for Atmospheric Research (a home for NCAR software and projects)
+
+### Example (public) GitHub organization READMEs:
+
+- **[Outdoor Equity](https://github.com/outdoor-equity)**, by Halina Do-Linh & Clarissa Boyajian (MEDS 2022 Capstone project) 
+- **[CASAschools](https://github.com/CASAschools)**, by Liane Chen, Charlie Curtin, Kristina Glass & Hazel Vaquero (MEDS 2024 Capstone project)
+- **[NMFS Open Science](https://github.com/nmfs-opensci)**, by the National Marine Fisheries Service (contains work which supports open science and open data literacy across NOAA fisheries)
+- **[NASA Goddard Institute for Space Studies](https://github.com/NASA-GISS)**, by NASA (laboratory in the Earth Sciences Division of NASA’s Goddard Space Flight Center)
+- **[GitHub](https://github.com/github)**, by GitHub (yes, GitHub is built on GitHub!)
diff --git a/sections/repo-READMEs.qmd b/sections/repo-READMEs.qmd
@@ -0,0 +1,75 @@
+---
+format: 
+  html:
+    theme: meds-website-styles.scss
+    mainfont: Nunito
+    toc: true
+    toc-location: left
+    toc-depth: 2
+    smooth-scroll: true
+---
+
+## Repository-level READMEs
+
+**You should always include a [README](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) in the root directory of your GitHub repositories.** A README is typically the first item that visitors will see when they arrive at your repository. This makes them the perfect place to tell people what your project is, why its useful, and how to get started using it. What you include in a given README will look different depending on the project, but here are some guidelines for getting started:
+
+### Things you should *always* include in your GitHub repository READMEs: {#always-include}
+
+::: {.callout-important}
+These core elements are required for *all* MEDS-related homework assignments and projects.
+:::
+
+1. [**A short, but descriptive title**]{.teal-text} 
+    - A README’s title is set to the repository name by default - change this!
+2. [**A brief explanation of the repository's purpose**]{.teal-text} 
+    - Paragraphs or a bulleted list are both acceptable options
+    - You may include an image or logo that represents the project
+3. [**A concise description of what’s housed in the repository**]{.teal-text} 
+    - This includes information about the repository structure or file organization
+4. [**Details regarding data access**]{.teal-text} 
+   - Any necessary information on where data lives (e.g. is it housed in the repo, on a server, in a library/package etc.) and how to access it in order to run the code
+5. [**A list of authors or current contributors (for collaborative work)**]{.teal-text} 
+    - Consider hyperlinking collaborators' GitHub profiles or other professional profile
+6. [**References**]{.teal-text}  
+    - In an appropriate, consistent format, including links
+    - Don't forget to add references for data sets too
+
+### Things you should consider including, but may vary depending on the goals and complexity of the project: {#consider-including}
+
+1. [**How to install or where to start**]{.teal-text} 
+    - Does your repository contain software that users will need to download or install? Do users access your software via a web browser? Do they need to install any dependencies? Do users need to clone your repository? etc.
+2. [**A quick demo**]{.teal-text} 
+    - Related to #1, above. Its important to keep this concise! You may include images. Any long-form instructional documentation is best moved to the repository's wiki
+3. [**What do do if a bug is spotted**]{.teal-text} 
+    - Make mention of GitHub issues and what information a user should include in an issue
+4. [**Contributing**]{.teal-text} 
+    - Do you welcome contributions from others? If so, its important to explain how one might contribute (e.g. fork & pull request, open an issue, both?)
+5. [**License**]{.teal-text} 
+    - Important for allowing others to reuse your work (which is copyrighted, by default; [read about what it means when no license is available](https://choosealicense.com/no-permission/))
+    - What license you choose depends on what type of work you are trying to license. There are different licenses used for code/software, content, and data. Some helpful resources for getting started: 
+        a. *Licensing code / software:* check out this page,[ Choose an open source license](https://choosealicense.com/), by GitHub. A couple popular options for software include [MIT License](https://choosealicense.com/licenses/mit/) and [GNU GPLv3](https://choosealicense.com/licenses/gpl-3.0/)
+        b. *Licensing content (i.e. non-software):* check out this page, [About CC Licenses](https://creativecommons.org/share-your-work/cclicenses/), by Creative Commons. A few good CC options for non-software content include [CC BY](https://creativecommons.org/licenses/by/4.0/?ref=chooser-v1), [CC BY-SA](https://creativecommons.org/licenses/by-sa/4.0/), and [CC BY-NC](https://creativecommons.org/licenses/by-nc/4.0/).
+        c. *Licensing data:* You'll chat more about this in [EDS 213 (Databases and Data Management)](https://bren.ucsb.edu/courses/eds-213)!
+6. [**Acknowledgements**]{.teal-text}
+    - Provide reference to any other individuals or sources that supported the development of the repository. For example, did you fork an existing repository? Did the work have any funding sources? Were there individuals you consulted with or were inspired by?
+
+::: {.callout-note}
+## Keep READMEs concise
+
+While it may be tempting to provide as much information as you possibly can into your README, it might not necessarily be the right home for *everything* (see the [Wikis](#wikis) section, below). I find this advice from [Kira Oakley](https://github.com/hackergrrl) in her article, [Art of README](https://github.com/hackergrrl/art-of-readme?tab=readme-ov-file#readme) to be a helpful reminder:
+
+>"The lack of a README is a powerful red flag, but even a lengthy README is not indicative of there being high quality. The ideal README is as short as it can be without being any shorter. Detailed documentation is good -- make separate pages for it! -- but keep your README succinct."
+
+:::
+
+### Example GitHub repository READMEs: {#example-repo-readmes}
+
+Each project is different and so is its README. As you browse through different repositories you will see that not all of them have the same sections. However, they all offer a clear starting point for a newcomer to understand what the project is about. Here are some GitHub repositories with READMEs we like:
+
+- **[strava-dashboard](https://github.com/samanthacsik/strava-dashboard)**, by Samantha Csik - code for a Shiny dashboard
+- **[EDS-240-data-viz](https://github.com/samanthacsik/EDS-240-data-viz)**, by Samantha Csik - code for a course website
+- **[thomas-fire](https://github.com/annaramji/thomas-fire)**, by Anna Ramji - a MEDS student project
+- **[xarray](https://github.com/pydata/xarray)** - a Python package for working with multidimensional arrays and datasets
+- **[palmerpenguins](https://github.com/allisonhorst/palmerpenguins/)** - an R package that contains teaching data
+- **[metajam](https://github.com/NCEAS/metajam)** - an R package for downloading and reading in metadata from repositories in the DataONE network
+- **[awesome-readme](https://github.com/matiassingers/awesome-readme)**, by Matias Singers - a curated list of awesome READMEs