Merge pull request #9 from NCEAS/wg-setup

Working Group Setup Instructions

_quarto.yml

@@ -39,11 +39,13 @@ website:
         menu:
           - text: "People"
             href: staff.qmd
-          - text: "Internal Onboarding"
-            href: team-onboarding.qmd
           - text: "Data Acquisition"
             href: data-acquisition.qmd
-          - text: "Deploy Shiny Apps"
+          - text: "Internal - Team Onboarding"
+            href: team-onboarding.qmd
+          - text: "Internal - Group Setup"
+            href: wg-setup.qmd
+          - text: "Internal - Deploy Shiny Apps"
             href: shiny-server.qmd
     right:
       - icon: github

wg-setup.qmd

@@ -0,0 +1,101 @@
+---
+title: "Working Group Setup Checklist"
+---
+
+:::callout-note
+Please note that the following checklist of working group setup steps is meant to serve as internal documentation _only_! Our team will be taking these steps on your behalf when you are funded so none of these steps are things you (a working member/PI) need to handle.
+
+Feel free to [contact us](https://nceas.github.io/scicomp.github.io/staff.html) if you find these instructions useful and want to apply them to non-working group contexts!
+:::
+
+When new working groups are funded, our team takes a number of setup steps to create some of the infrastructure that past groups have requested/found useful. This is mainly an attempt to help the group avoid spending their precious in-person meeting time doing relatively dry technical steps that we can easily accomplish early-on. Some of these steps also set a useful 'tone' in terms of facilitating groups' adherence to reproducibility best practices.
+
+
+## Google Shared Drive
+
+Many groups gravitate towards using Google Drive for storing data, relevant scientific literature, and (eventually) manuscript drafts. One advantage of a true Shared Drive over simply creating a folder and sharing that is that the distributed ownership of the Shared Drive makes it very difficult to accidentally delete/lose important files.
+
+Some groups have experience serious heartbreak when one member's Google identity gets closed by their institution and all files/folders created by that member vanish. A Shared Drive makes this horror story an impossibility.
+
+### Creating the Shared Drive
+
+Our `@nceas.ucsb.edu` email addresses are empowered to create Shared Drives. Navigate to your Google Drive, then in the left sidebar click "Shared drives". Once there you can click the "+ New" button to create a brand new Shared Drive.
+
+The naming convention you should use is: LTER-WG_`WG-NAME`
+
+Note that for groups with longer names you will want to abbreviate so that the Shared Drive name doesn't get ambiguously cropped in a default browser window.
+
+### Adding Users
+
+Once the Shared Drive exists, add the following people as "Content Managers":
+
+- <u>All</u> members of the NCEAS Scientific Computing team
+- Marty Downs (LTER Network Office Director)
+- Thomas Hetmank (NCEAS Programmer/Analyst)
+
+When you reach out to the working groups you can also make a note of their emails and add them as well though you may want to first tell them about the Shared Drive before sending them a semi-random Shared Drive invite.
+
+### Content Creation
+
+We want to use as light a touch as possible here to make sure that groups feel empowered to make their Shared Drive whatever they need it to be but there are a few things we can do.
+
+1. Make a "Data" folder
+2. Add a [data log template GoogleSheet](https://docs.google.com/spreadsheets/d/1WOH_EPUF0XL9qutkLgia--YANieXFFX8Goic8LGcVgI/edit#gid=0) to the Data folder
+
+In the past we have also added a [README GoogleDoc](https://docs.google.com/document/d/1q6ajgYjvfiaPH2PFsbybOxCWP5JX64nRMRMc7ABzagc/edit#heading=h.kyp2vjxt438v) but it is unclear to what extent this is used by groups. We may want to look into whether this is useful and--if not--how we can improve it.
+
+## GitHub Repository
+
+We encourage all groups to engage with GitHub for--at minimum--storing their final code products. We have found that creating a GitHub repository at this stage tends to increase adoption of GitHub and is therefore very much worthwhile even if no group members use it at the time that their group gets funded.
+
+### Initialize Repository
+
+Make a repository in the [LTER GitHub Organization](https://github.com/lter) with the following information:
+
+1. Create a name that fits one of the following naming conventions
+    - For full working groups (3-4 meetings): "lterwg-`abbreviated-group-name`"
+    - For SPARC groups (1 meeting): "lter-sparc-`abbreviated-group-name`"
+2. Set the "Description" to the title of the working group
+    - As indicated on [the LTER Network Office website](https://lternet.edu/current-working-groups/)
+3. Add a README
+4. Create a `.gitignore` <u>using the R template</u>
+    - R is the most common working group language and the `.gitignore` is easily changed in the event the group is primarily using a different language
+
+### Edit README
+
+Edit the default README with the following content:
+
+- Make a top level markdown heading (i.e., one `#`) with the title of the group
+- Make a second level markdown heading (`##`) called "Project Summary"
+    - Include a link to the group-specific page on [the LTER Network Office website](https://lternet.edu/current-working-groups/)
+- Make a second level markdown heading called "Supplementary Resources"
+    - Add a link to [the home page](https://nceas.github.io/scicomp.github.io/) of the NCEAS Scientific Computing team (i.e., the home page of _this_ website!)
+
+Note that you can make these edits directly from GitHub so you don't need to worry about cloning at this stage!
+
+### Edit `.gitignore`
+
+If you used the R template then this is basically ready to go but we can make two small edits that are convenient for many groups (and easily undone for those groups that decide to do so).
+
+1. Add `.DS_Store`
+
+This file type (short for "Desktop Services Store") is created by the Apple macOS operating system that stores visual information (e.g., icon positions, view options, etc.). In other words, it is a file that is completely irrelevant to reproducibility in a coding context and there will be one in _every_ folder for Mac users. By ignoring it when we create the GitHub repository we can guarantee that no group members accidentally commit these useless (in this context) files and in so doing add clutter to their repository.
+
+2. Add a wildcard `*.Rproj` 
+
+There is some debate about whether to ignore the .Rproj (see [our summary of this discussion](https://nceas.github.io/scicomp-workshop-collaborative-coding/git_ignore.html#should-you-ignore-the-.rproj-file) from our GitHub workshop materials) but for working groups _the default position is that we should ignore it_. There are two reasons to do this. **First**, working group members may change the name of the project on their local computer and then commit their uniquely-named .Rproj file. Taken to an extreme this means that there may be one .Rproj / user which can be confusing to some users and is not (in our opinion) very aesthetically pleasing. **Second** if groups commit a .Rproj and then later delete it, anyone who pulls that change will delete their cloned repository automatically (similar to a snake eating its own tail). By ignoring the .Rproj from the outset we can avoid this possisbility entirely.
+
+## NCEAS' Server
+
+Some groups wind up doing computationally-intense work (e.g., machine learning, spatial data wrangling, etc.). Such groups often find it useful to get set up on NCEAS' server "Aurora" to leverage the greater computing power to do these heavy operations relatively quickly. However, because adoption/need for this is somewhat mixed we _do not_ recommend creating a server group for every group before they request one.
+
+Instead, gage group interest and need and when it becomes relevant we can do the setup steps listed below. Note that we have a nice [group-facing server tutorial](https://nceas.github.io/scicomp-workshop-collaborative-coding/server.html) in our GitHub workshop materials.
+
+1. Reach out to Thomas Hetmank / Nick Outin to get a group made on the server for this working group
+2. Make sure that NCEAS Scientific Computing team staff are added as members
+3. Make a folder in the "shares" folder for this group
+4. Gather emails from all interested working group members and get them added to the Aurora group
+
+## Google Group
+
+There is ongoing discussion within the larger NCEAS administration that this task may become something handled by NCEAS' IT team so we will leave out our setup instructions at this time.