Modify Openscapes

Modify Getting Started, Organize, and Add Content chapters for Openscapes

_quarto.yml

@@ -65,9 +65,9 @@ website:
           - content/Resources.qmd
       - section: "NMFS Open Science Directions"
         contents:
-          - content/NMFS_OpenSciDirections/Intro.qmd
+          - content/NMFS_OpenSciDirections/Getting-Started.qmd
+          - content/NMFS_OpenSciDirections/organize.qmd
           - content/NMFS_OpenSciDirections/add-content.qmd
-          - content/NMFS_OpenSciDirections/customizing.qmd
           - content/NMFS_OpenSciDirections/rendering.qmd
           - content/NMFS_OpenSciDirections/rmarkdown.Rmd
           - content/NMFS_OpenSciDirections/code.qmd

content/NMFS_OpenSciDirections/Getting-Started.qmd

@@ -0,0 +1,53 @@
+---
+title: Getting Started
+---
+
+## Getting Started in Open Science
+
+Open Science is a movement to make scientific research (including publications, data, software) transparent and accessible so that knowledge is shared. Here we will provide steps to get started; in future sections we will provide additional details on specific tasks/projects
+
+1.  Embrace the Open Science Mindset! Learn more about this approach and why it matters at [Openscapes.org](openscapes.org) and the [Openscapes Approach Guide](https://openscapes.github.io/approach-guide/approach/).
+
+2.  Add Software Tools
+
+    1.  [Github Desktop](https://desktop.github.com/)
+
+    2.  [RStudio](https://www.rstudio.com/products/rstudio/download/#download) (v2022.07.2 build 576 or later)
+
+    3.  [R](https://www.r-project.org/)
+
+    4.  Create a [Github Login](https://github.com/)
+
+3.  Create a Repository using one of the following examples:
+
+    -   Create a Repository from a Template
+
+        -   [PAM Lab Manual Template](https://nmfs-ost.github.io/PAM_template_lab_manual/)- scroll down & follow directions 'How to use this template'
+
+        -   Consider one of [Eli Holme's templates](https://github.com/orgs/nmfs-opensci/repositories?q=&type=template&language=&sort=)
+
+    -   Create a New (or test) Repository in Github (see help [here](https://docs.github.com/en/get-started/quickstart/create-a-repo))
+
+4.  Clone your Test Repository to your local computer using Github Desktop:
+
+    1.  File -\> Clone Repository -\> URL
+
+    2.  Copy URL of your Test Repository on Github and save to your Documents -\> Github folder using the defaults. See [Introduction to Git/Github tutorial](https://rverse-tutorials.github.io/PSAW-2022/) for more help.
+
+5.  Open project in RStudio. In the upper right hand corner of RStudio, select 'New Project' in the drop-down menu to add a new R Project from an Existing Project. Browse to find the appropriate folder in Documents-\> Github. In the lower right section of RStudio, select 'Files' and you will see the README.md file, which appears on the home page on your Github repository site.
+
+6.  Modify the README.md file. Open this file and add text and possibly a link to this document. Save the file. If you are using the latest version of RStudio (with quarto), you can modify your file using the Source Code or the Visual Editor. This is an RMarkdown file, so you can use R markdown language, or, if you prefer, you can use the visual editor which is more user-friendly. If you copy/paste an existing document into the visual editor, much of the existing formatting will be retained.
+
+7.  Commit & Push to Github. Open your project in Github Desktop; Github desktop will identify the changes you made (refresh if necessary). At the bottom left, describe the modifications you made to the document, and then select 'commit'. Once the commit goes through-- select 'Push to Origin' at the top. This will push changes to your Github repository.
+
+8.  Open your Github repository and check out the changes on your README at the bottom of the page!
+
+9.  Adopt this process as your daily habit of working on your projects locally and saving your data to Github.
+
+For more information, see:
+
+[Introduction to Git/Github Tutorial](https://rverse-tutorials.github.io/PSAW-2022/) (Eli Holmes, NMFS)
+
+[Git for Humans](https://youtu.be/eWxxfttcMts) (Alice Bartlett)
+
+[Happy Git with R](https://happygitwithr.com/) (Jenny Bryan)

content/NMFS_OpenSciDirections/add-content.qmd

@@ -1,25 +1,60 @@
 ---
-title: Customize
+title: Customize Content
 ---
 
-## Edit and add your pages
+You can customize your content by (1) Modifying existing content, or (2) creating your own content. For examples, we will assume a folder structure such as that in the [PAM Template Lab Manual](https://github.com/nmfs-ost/PAM_template_lab_manual).
 
-Edit the qmd or md files in the `content` folder. qmd files can include code (R, Python, Julia) and lots of Quarto markdown bells and whistles (like call-outs, cross-references, auto-citations and much more).
+## Modify Existing Content
 
-Each page should start with 
-```
----
-title: your title
----
-```
-and the first header will be the 2nd level, so `## `. Note, there are situations where you leave off
-```
----
-title: your title
----
-```
-and start the qmd file with a level header `# `, but if using the default title yaml (in the `---` fence) is a good habit since it makes it easy for Quarto convert your qmd file to other formats (like into a presentation).
+Here are basic instructions for modifying existing content, such as the example pages provided in the [PAM Template Lab Manual](https://github.com/nmfs-ost/PAM_template_lab_manual): 1) Ensure that you have cloned the Github Repository using Github Desktop, and that you have created an RStudio project, following directions outlined [here](https://sael-swfsc.github.io/OpenScience/content/GithubDesktop.html).
+
+1)  Open your RStudio project (here we will assume it is a clone of the PAM Template Lab Manual), and navigate to the 'content' folder (lower right hand side of RStudio, Files Tab). As an example, we will change the "/content/Hardware.qmd" file. First, read the information in the page to understand the intended content. To start, we will organize different subheadings within this page.
+
+    ![](images/findHardwareFile-01.JPG){width="294"}
+
+2)  Identify Sub-Headings. In this example, we will want to identify different types of Hardware used by our particular lab. In this example, we will want the following categories: "PAM Gliders", "Drifting Recorders", "Towed Arrays", and "Handheld Hydrophones".
+
+    -   Using the **Source** editor, use \# to indicate Heading 1 style, \## for Heading 2 Style, etc.
+
+    -   Using the **Visual** editor, use the dropdown menu to select the Heading Style
+
+3)  Add Content. Most content will consist of text, with some images, hyperlinks, and occasional tables. To start, we recommend identifying the content you would like to put in there, and identify the Point of Contact (POC). As an example, we may put the following text:
+
+    POC: Jane Doe. General description of Hardware, links to online content (vendor specification page, relevant online content), instructions for build or maintain hardware (or links to that information), links to inventory, etc.
+
+4)  Once your outline is developed, fill in the content. IF someone else will collate the content– they can create it in a separate document to be copied/pasted here, or they can directly modify this page.
+
+5)  If you find you need separate pages for each sub-heading (instead of one long subheading), then create New Content, and link the new content to the \_quarto.yml.
+
+6)  When you are finished modifying your document and Project, push changes to Github using Github Desktop (see instructions here).
+
+## Create New Content
+
+Again, assuming you have an RStudio project for your Github Repository, such as the example provided in the [PAM Template Lab Manual](https://github.com/nmfs-ost/PAM_template_lab_manual): 1) Ensure that you have cloned the Github Repository using Github Desktop, and that you have created an RStudio project, following directions outlined [here](https://sael-swfsc.github.io/OpenScience/content/GithubDesktop.html).
+
+1.   Open your RStudio project (here we will assume it is a clone of the PAM Template Lab Manual), and navigate to the 'content' folder (lower right hand side of RStudio, Files Tab). Select **New Blank File**, and in the drop-down, select **Quarto Document**. Then give your file a logical and descriptive name.
+
+    ![](images/newQuartoDoc.JPG){width="328"}
+
+2.  Using the **Source** editor, create a title header with the text you would like as your primary Header for this page (will appear as Header 1).
+
+    ![](images/newPageTitle.JPG){width="282"}
+
+3.  Add content below the header section, using either the **Source** or **Visual** editor in RStudio.
+
+4.  Add your new content to the \_quarto.yml
+
+5.  When you are finished modifying your document and Project, push changes to Github using Github Desktop (see instructions here).
+
+## Examples
+
+Looking at other people's Quarto code is a great way to figure out how to do stuff. Most will have a link to a GitHub repo where you can see the raw code. Look for a link to edit page or see source code. This will usually be on the right. Or look for the GitHub icon somewhere.
+
+-   [Quarto gallery](https://quarto.org/docs/gallery/)
+-   [nmfs-openscapes](https://nmfs-openscapes.github.io/)
+-   [Faye lab manual](https://thefaylab.github.io/lab-manual/)
+-   [quarto-titlepages](https://nmfs-opensci.github.io/quarto_titlepages/) Note the link to edit is broken. Go to repo and look in `documentation` directory.
 
-## Add your pages the project
+## Resources
 
-* Add the files to `_quarto.yml`
+-   [Quarto documentation](https://quarto.org/docs/guide/).

content/NMFS_OpenSciDirections/organize.qmd

@@ -0,0 +1,33 @@
+---
+title: Organize with Yaml
+---
+
+## How to Organize your Quarto Book
+
+Quarto Books are combinations of multiple documents (chapters) into a single manuscript in one or more formats (HTML, PDF, Word Doc, etc). Our example below is based on the [PAM_template_lab_manual](https://nmfs-ost.github.io/PAM_template_lab_manual/):
+
+**index.qmd**- the index.qmd file is in the root director for your project, and serves as the Home Page for a website. This file is mandatory.
+
+**\_quarto.yml**- the \_quarto.yml is the configuration file for your project, and is also located in the root directory. The \_quarto.yml provides information regarding overall formatting and structure of pages within the larger document.
+
+**README.md**- Markdown file that serves as the readme for the github repository.
+
+**content folder**- This folder contains the individual pages for your document. Alternative names for this folder are sometimes used, but we have found that the term 'content' is less confusing that frequently used alternatives. Here we recommend using this for consistency.
+
+### What is a YAML?
+
+YAML is a human-readable data serialization language commonly used for configuration files. YAML works with multiple programming languages, and also allows users to add comments to their data (useful for documentation). YAML does require very specific indentation, mapping, etc. It is helpful to use a [yaml checker](https://yamlchecker.com/) to be sure your yaml does not have errors.
+
+Quarto books/websites contain a \_quarto.yml file, which is the website's configuration file. It is essentially metadata for the website that includes the order that the pages/chapters will be in. This is where you organize your site. Here is a side-by-side example:
+
+![](images/quarto-yml-site-side-by-side3.png)
+
+Learn more, [here](https://openscapes.github.io/quarto-website-tutorial/explore.html).
+
+## Resources
+
+-   [Yaml Checker](https://yamlchecker.com/)
+
+-   [Quarto Yaml Options (HTML)](https://quarto.org/docs/reference/formats/html.html)
+
+-   [Quarto Book Structure](https://quarto.org/docs/books/book-structure.html)