Merge pull request #4 from cct-datascience/remove-shortcodes

Remove var shortcodes

README.md

@@ -14,22 +14,34 @@ This is a work-in-progress, but will eventually be a template repo that contains
 
 -   Bahlai lab policies: <https://github.com/BahlaiLab/Policies>
 
-## Things to edit
+-   Tendler, B.C., Welland, M., Miller, K.L., The WIN Handbook Team, 2023.
+    Why every lab needs a handbook.
+    eLife 12, e88853.
+    <https://doi.org/10.7554/eLife.88853>
 
-I'll turn this into instructions later, but here's a running list of things you'll need to edit after using this template:
+## How to use this template
 
--   Everything in `_variables.yml`
+1.  Click the green "Use this template" button to create a copy in your own GitHub organization (or personal account)
+2.  Edit the `_quarto.yml` configuration file to customize it to your group
+3.  Edit the `.qmd` files to customize it to your group
+4.  Publish to GitHub Pages
 
--   `author:` in `_quarto.yml` (can't do lists with shortcodes)
+### Things to edit
 
--   `cover.png` and `cover-image` in `_quarto.yml` if you want a lab logo.
+-   Do a find and replace everywhere (cmd + shift + F in RStudio) for the following: "GROUP_NAME", "PI_NAME", and "PI_EMAIL".
 
--   `repo_url` in `_quarto.yml`
+-   Edit the `repo_url:` key in `_quarto.yml` to be the URL to *your* copy of this template on *your* GitHub organization or account
+
+-   Edit the authors information in `_quarto.yml` (e.g. name and ORCID)
+
+-   Potentially add, remove, or re-order chapters by editing the `chapters:` key in `_quarto.yml`
 
 -   Red callout boxes titled "Group Edit" hold suggestions for what content to include on that page/section.
-    These should be deleted or commented out once the edits happen.
+    These should be deleted once the edits happen.
+
+-   **All text** in the `.qmd` documents is boilerplate or example text and intended to be edited to some extent to customize it for your group.
 
-## To publish
+### To publish
 
 You only have to do this once.
 

_quarto.yml

@@ -3,19 +3,17 @@ project:
 execute: 
   freeze: auto
 book:
-  title: "{{< var group_name >}} Handbook"
-  # cover-image: "cover.png"
+  title: "GROUP_NAME Handbook"
   search: true
   repo-url: https://github.com/cct-datascience/group-handbook-template
   repo-actions: [edit, issue]
   author: 
-    - name: Jim Jones
+    - name: PI_NAME
       orcid: 0000-0000-0000-0000
-    - name: Student Scott
-    - name: Staff Member Mary
+    #add all contributors as additional authors
   date: "11/28/2023"
   chapters:
-    - index.qmd
+    - index.qmd #the landing page *must* be called 'index.qmd'
     - contributing.qmd
     - href: code-of-conduct.qmd
       text: "Code of Conduct"
@@ -31,7 +29,6 @@ bibliography: references.bib
 format:
   html:
     number-depth: 1
-    link-external-icon: true
     link-external-newwindow: true
     theme: 
       light: flatly

authorship.qmd

@@ -15,5 +15,5 @@ Some ideas of things to discuss:
 
 -   Under what circumstances, if any, should authors be removed from a project?
 
--   Are there any circumstances where {{< var pi_name >}} wouldn't be an author on a student/mentee paper?
+-   Are there any circumstances where PI_NAME wouldn't be an author on a student/mentee paper?
 :::

code-of-conduct.qmd

@@ -1,4 +1,4 @@
-# {{< var group_name >}} Code of Conduct
+# GROUP_NAME Code of Conduct
 
 ::: callout-important
 ## Group Edit
@@ -9,12 +9,12 @@ Be sure to credit any sources you are inspired by!
 :::
 
 Science is hard, and the work of making sure science isn't harder than it needs to be is on all of us.
-We create our culture, and in the {{< var group_name >}}, our culture is inclusive.
+We create our culture, and in the GROUP_NAME, our culture is inclusive.
 
 We value the participation of every member of our community and want to ensure an that every lab member and collaborator has a positive, educational experience unhindered by unnecessary challenges caused by non-inclusive behavior.
-Accordingly, everyone who participates in any {{< var group_name >}} project is expected to show respect and courtesy to other community members at all times.
+Accordingly, everyone who participates in any GROUP_NAME project is expected to show respect and courtesy to other community members at all times.
 
-{{< var pi_name >}} as head of the {{< var group_name >}}, and all lab members, are dedicated to a ***harassment and discrimination-free experience for everyone.*** Discrimination or harassment based on racial or ethnic background, citizenship status, religion (or lack thereof), political affiliation, gender identity/expression, sexual orientation, dis/ability status, appearance or body size will not be tolerated.
+PI_NAME as head of the GROUP_NAME, and all lab members, are dedicated to a ***harassment and discrimination-free experience for everyone.*** Discrimination or harassment based on racial or ethnic background, citizenship status, religion (or lack thereof), political affiliation, gender identity/expression, sexual orientation, dis/ability status, appearance or body size will not be tolerated.
 **We do not tolerate harassment or discrimination by and/or of members of our community in any form**.
 
 We are particularly motivated to support new and/or anxious collaborators, people who are looking to learn and develop their skills, and anyone who has experienced discrimination in the past.
@@ -49,12 +49,12 @@ Unacceptable behavior includes offensive verbal comments related to gender, sexu
 
 ***Participants asked to stop any harassing or discriminatory behavior are expected to comply immediately.***
 
-Members of the community who violate these rules—no matter how much they have contributed to the {{< var group_name >}}, or how specialized their skill set—will be approached by {{< var pi_name >}}.
-If inappropriate behavior persists after a discussion with {{< var pi_name >}}, the issue will be escalated according to procedures laid out by the relevant entities in University of Arizona's [Office of Institutional Equity](https://equity.arizona.edu/)
+Members of the community who violate these rules—no matter how much they have contributed to the GROUP_NAME, or how specialized their skill set—will be approached by PI_NAME.
+If inappropriate behavior persists after a discussion with PI_NAME, the issue will be escalated according to procedures laid out by the relevant entities in University of Arizona's [Office of Institutional Equity](https://equity.arizona.edu/)
 
-**To report an issue** please contact [{{< var pi_name >}}](mailto:{{< var pi_contact >}}).
+**To report an issue** please contact [PI_NAME](mailto:PI_EMAIL).
 All communication will be treated as confidential.
-If you feel you cannot contact {{< var pi_name >}}, contact the [Office of Institutional Equity](https://equity.arizona.edu/reporting)
+If you feel you cannot contact PI_NAME, contact the [Office of Institutional Equity](https://equity.arizona.edu/reporting)
 
 ## University of Arizona Policies
 

contributing.qmd

@@ -9,7 +9,7 @@ editor:
 
 Prerequisites:
 
--   Create an account on GitHub if you don't already have one.
+-   Create an account on [GitHub](https://github.com/) if you don't already have one.
 -   Basic understanding of [markdown](https://quarto.org/docs/authoring/markdown-basics.html).
 -   Optionally, knowledge of [Quarto](https://quarto.org/).
 
@@ -23,7 +23,7 @@ To make an edit directly on GitHub, click the "{{< fa brands github >}} Edit thi
 This will open a page where you can make edits.
 When you are done, click the green "Commit changes..." button.
 If you do not have the ability to push directly to the GitHub repository it may prompt you to create a fork and submit changes as a pull request.
-Your edits won't be "live" until someone (such as {{< var pi_name >}}) merges these changes.
+Your edits won't be "live" until someone (such as **PI_NAME**) merges these changes.
 Don't worry if you don't know what "fork" and "pull request" mean yet—you should still be able to make edits this way!
 
 ### More substantial edits or new sections

group-expectations.qmd

@@ -25,7 +25,8 @@ Some discussion topics to get you started:
 
 -   What roles are there in your group that may have different expectations?
 
-    -   E.g. undergraduates, postdocs, staff
+    -   Below, roles are split into "mentor" and "mentee", but maybe there are actually more roles in your lab
+    -   E.g. undergraduate, grad student, postdoc, staff, etc.
 :::
 
 ## Mentee expectations

index.qmd

@@ -1,11 +1,13 @@
+<!-- NOTE: do not re-name this file!  It has to be called index.qmd -->
+
 # Welcome! {.unnumbered}
 
 ::: callout-note
 Note to lab members: this document is a work in progress and may change.
 It is your responsibility to be familiar with the content, so you should review these policies regularly.
 :::
 
-Welcome to the {{< var group_name >}}.
+Welcome to the GROUP_NAME.
 In this lab, we study ...
 
 ::: callout-important

offboarding.qmd

@@ -21,13 +21,17 @@ Here are some discussion topics to get you started though:
 
 -   What is the timeline for all of this?
     Don't wait until the last week of work to complete all these tasks!
+
+-   Why is offboarding important to this group?
+    To get feedback on mentoring?
+    To make sure there is continuity of projects?
 :::
 
-Offboarding is important to our group because we want to get feedback and also not lose your data and stuff
+Offboarding is important to our group because ...
 
 Steps to take:
 
-1.  Make sure all of your code is in repositories in the {{< var group_name >}} GitHub organization
+1.  Make sure all of your code is in repositories in the group's GitHub organization
 2.  Make sure each project has a README file explaining what it is, how to reproduce results, and includes metadata for any data collected (e.g. what do column names mean and what units are they in?)
 3.  Schedule an exit interview
 4.  More steps...