Merge pull request #52 from CollectionBuilder/sheets-docs

sheets docs

docs/metadata/gh_metadata.md

@@ -1,27 +1,31 @@
 ---
-title: GH Metadata
+title: GH and SHEETs Metadata
 parent: Metadata
 nav_order: 1
 ---
 
-# CollectionBuilder-GH Metadata
+# CollectionBuilder-GH and SHEETS Metadata
+
+{:.alert .alert-yellow}
+**Note**: CollectionBuilder-GH and CollectionBuilder-SHEETS use the same metadata template. SHEETS allows you to update collections directly from a Google Sheet (making it ideal for prototyping or collaborating and seeing changes in real time), while GH requires that you upload your metadata spreadsheet to your repository (making it ideal for teaching and learning GitHub, Git, and other web workflows).
 
 ## Metadata Template
 
-If you are starting your collection from scratch, the easiest way to ensure you have the required fields is to create your metadata using the CollectionBuilder-GH metadata template. 
-The template is available on Google Sheets via the link below (make sure you're logged in to Google Drive, then open the template and click the File menu and select "Make a Copy" to get started), or in your CollectionBuilder-GH project repository as "_data/metadata-template.csv".
+If you are starting your collection from scratch, the easiest way to ensure you have the required fields is to create your metadata using the CollectionBuilder-GH / CollectionBuilder-SHEETS metadata template (note that this metadata template will work for *both* GH and SHEETS). 
+The template is available on Google Sheets via the link below (make sure you're logged in to Google Drive, then open the template and click the File menu and select "Make a Copy" to get started)
+It is also available in your CollectionBuilder-GH project repository as "_data/metadata-template.csv".
 This template is a starting point--fill in only what is relevant for your content and feel free to add more columns!
 
 If transforming existing metadata, you do **not** need to exactly match the CollectionBuilder template. 
 Just ensure that you create the required fields following the conventions described below. 
 
-[CollectionBuilder-GH Metadata Template](https://docs.google.com/spreadsheets/d/1Uv9ytll0hysMOH1j-VL1lZx6PWvc1zf3L35sK_4IuzI/copy?usp=sharing){:.btn .btn-purple target="_blank" rel="noopener"}
+[CollectionBuilder-GH / CollectionBuilder-SHEETS Metadata Template](https://docs.google.com/spreadsheets/d/1Uv9ytll0hysMOH1j-VL1lZx6PWvc1zf3L35sK_4IuzI/copy?usp=sharing){:.btn .btn-purple target="_blank" rel="noopener"}
 
 The guidelines below provide details about each field.
 
 -----
 
-## Required Fields for CollectionBuilder-GH
+## Required Fields for CollectionBuilder-GH and SHEETS
 
 Without values in the fields below, CollectionBuilder will not work properly.
 
@@ -41,6 +45,9 @@ Without values in the fields below, CollectionBuilder will not work properly.
     - Example value for an external link for a "record" item type: `https://www.doi.org/10.1577/M02-113`
 - *Tip:* check [Get List of Filenames]({{ '/docs/extras/utilities/#get-list-of-filenames' | relative_url }}) for quick methods to fill in the filename field!
 
+{:.alert .alert-red}
+**Note**: Are you using SHEETS to prototype a site? Your objects' filenames *must* be full URLs to files hosted externally to your project!
+
 ### title: 
 
 - The title field is used to indicate the name of an item. This should be a short, descriptive set of words that identify the item. Each item may only have one title.

docs/objects/gh-objects.md

@@ -1,21 +1,24 @@
 ---
-title: Objects for GH
+title: Objects for GH and SHEETS
 parent: Objects
 nav_order: 1
 ---
 
-# Collection Objects for CollectionBuilder-GH
+# Collection Objects for CollectionBuilder-GH and SHEETS
 
-Collectionbuilder-GH is designed for learning with small collections.
-To minimize barriers to getting started, GH has a simplified approach to collection objects. 
+**Collectionbuilder-GH** and **CollectionBuilder-SHEETS** are designed for learning with small collections.
+To minimize barriers to getting started, these templates take a simplified approach to collection objects. 
 
-GH supports a small set of object types including jpg, png, pdf, and mp3, plus externally hosted items via YouTube, Vimeo, and external links.
-All object files are placed in the "objects" folder directly in your project repository and will be committed to GitHub.
+GH and SHEETS support a small set of object types including jpg, png, pdf, and mp3, plus externally hosted items via YouTube, Vimeo, and external links.
 No access derivatives are generated, meaning the full sized objects you add to the project will be displayed on web pages through out the site, and no thumbnails are created for non-image items.
 
+Objects must be externally hosted for use in SHEETS prototype sites, but GH and permanent/collaborative SHEETS sites accept local as well as externally hosted object files.
+
+For local hosting, all object files are placed in the "objects" folder directly in your project repository and will be committed to GitHub.
+
 Prep your items in a folder together on your local machine, doing any object editing in advance of adding them to the project.
 
-## Object Guidelines for GH
+## Object Guidelines for GH and SHEETS
 
 - **Supported formats:** jpg, png, pdf, mp3 -- plus YouTube, Vimeo, and external links, but you won't have objects for those!
 - **File size:** since there are no thumbnails generated, keep your object files at a reasonable size for access on the web. This means you will usually not be using your full resolution versions! For example, jpeg images of about 1200px wide and PDFs less than 1 MB will work well. Larger objects (especially images) will slow load times and make your users download unnecessarily large data--so keep them to a web friendly size!
@@ -27,11 +30,11 @@ Check your View settings to show extensions!
 
 {:.alert .alert-purple }
 **Note:** 
-CB-GH is great for learning and prototyping--all your configuration and metadata is transferable to other CollectionBuilder templates.
+CB-GH and CB-SHEETS are great for learning, collaborating, and prototyping--all your configuration and metadata is transferable to other CollectionBuilder templates.
 If you are building a larger collection or featuring larger objects, you will run into its limitations--try using a smaller subset of your collection and smaller size images for your prototype, then migrate to the fully featured CollectionBuilder-CSV template later!
 CollectionBuilder-CSV enables generating derivatives and hosting objects outside of GitHub.
 
-## Add Objects to your GH Project
+## Add Objects to your GH and SHEETS Projects
 
 Once your digital objects are prepped in a folder with *good filenames and reasonable sizes*...
 You will upload your files into the "objects" folder in your project repository on GitHub.
@@ -43,3 +46,16 @@ Follow these steps:
 2. On the "objects" folder page, click the "Add file" button and select "Upload files" (appears to right side of page).
 3. Click "choose your files" and navigate to the location of your object files on your local machine, and select all the collection items. Or drag and drop all the files from your File Explorer / Finder into the GitHub page. Once the files are uploaded, they will appear listed on the web page.
 4. Scroll down to the "Commit changes" box, write a short commit message in the form (an appropriate message might be "add collection objects to project"), then click the green "Commit changes" button to add them to your repository. 
+
+## Host GH and SHEETS Objects Externally
+
+Consider hosting your objects files externally on the web using one of these solutions:
+
+- Host objects on your organization's server
+- Host objects on a platform such as [Digital Ocean](https://www.digitalocean.com/products/spaces){:target="_blank" rel="noopener"} or [Reclaim Hosting](https://reclaimhosting.com/){:target="_blank" rel="noopener"} (may require a fee)
+- Host objects [via GitHub pages](https://medium.com/@jeftachibiya360/how-to-host-images-for-your-website-on-github-a98d917284c5){:target="_blank" rel="noopener"} (free)
+
+{:.alert .alert-red}
+**Note**: Are you using SHEETS to prototype a site? Your objects *must* be made available externally!
+
+External links to your objects should be included in the filename column of your metadata spreadsheet. Please read our [Metadata Documentation](https://collectionbuilder.github.io/cb-docs/docs/metadata/gh_metadata/#filename){:target="_blank" rel="noopener"} to learn more about external item files.