Islandora · whikloj · Apr 18, 2019 · Mar 7, 2019 · Mar 7, 2019 · Mar 7, 2019
diff --git a/docs/alpaca/README.md b/docs/alpaca/README.md
diff --git a/docs/assets/Add content.jpg b/docs/assets/Add content.jpg
diff --git a/docs/assets/Add media.jpg b/docs/assets/Add media.jpg
diff --git a/docs/assets/Click media.jpg b/docs/assets/Click media.jpg
diff --git a/docs/assets/Final loaded image.jpg b/docs/assets/Final loaded image.jpg
diff --git a/docs/assets/Image option.png b/docs/assets/Image option.png
diff --git a/docs/assets/Under system select format.jpg b/docs/assets/Under system select format.jpg
diff --git a/docs/assets/add-content-collection.jpg b/docs/assets/add-content-collection.jpg
diff --git a/docs/assets/add-content-loading-media.jpg b/docs/assets/add-content-loading-media.jpg
diff --git a/docs/assets/add-media.jpg b/docs/assets/add-media.jpg
diff --git a/docs/assets/adding image.jpg b/docs/assets/adding image.jpg
diff --git a/docs/assets/adding-image.jpg b/docs/assets/adding-image.jpg
diff --git a/docs/assets/click-media.jpg b/docs/assets/click-media.jpg
diff --git a/docs/assets/collection-parent-node.jpg b/docs/assets/collection-parent-node.jpg
diff --git a/docs/assets/edit-photo-collection.jpg b/docs/assets/edit-photo-collection.jpg
diff --git a/docs/assets/final-loaded-image.jpg b/docs/assets/final-loaded-image.jpg
diff --git a/docs/assets/form-collection.jpg b/docs/assets/form-collection.jpg
diff --git a/docs/assets/image-option.png b/docs/assets/image-option.png
diff --git a/docs/assets/member-of-collection-selected.jpg b/docs/assets/member-of-collection-selected.jpg
diff --git a/docs/assets/member-of-collection.jpg b/docs/assets/member-of-collection.jpg
diff --git a/docs/assets/members-tab.png b/docs/assets/members-tab.png
diff --git a/docs/assets/repository item.jpg b/docs/assets/repository item.jpg
diff --git a/docs/assets/repository-item-collection.jpg b/docs/assets/repository-item-collection.jpg
diff --git a/docs/assets/repository-item.jpg b/docs/assets/repository-item.jpg
diff --git a/docs/assets/select-content-type-for-new-member.png b/docs/assets/select-content-type-for-new-member.png
diff --git a/docs/assets/snowfall-collection.jpg b/docs/assets/snowfall-collection.jpg
diff --git a/docs/assets/system-collection.jpg b/docs/assets/system-collection.jpg
diff --git a/docs/assets/under-system-select-format.jpg b/docs/assets/under-system-select-format.jpg
diff --git a/docs/chullo/README.md b/docs/chullo/README.md
diff --git a/docs/crayfish-commons/README.md b/docs/crayfish-commons/README.md
diff --git a/docs/crayfish/README.md b/docs/crayfish/README.md
diff --git a/docs/index.md b/docs/index.md
@@ -1,22 +1,7 @@
-# Islandora CLAW
-
-## Summary
-
 <a href="https://islandora.ca">Islandora</a> is an open-source repository framework, that combines a Drupal front-end
 with a Fedora repository. It is a solution for institutions who want an extremely flexible and configurable preservation repository without creating a lot of custom code.
 
-Islandora CLAW integrates [Drupal](https://www.drupal.org/) (currently, Drupal 8) and Duraspace's [Fedora Repository](https://wiki.duraspace.org/display/FF/Fedora+Repository+Home) project (currently, Fedora 5). Islandora CLAW is currently in beta. (todo: release section?)
-
-Islandora CLAW allows you to create nodes, media, files, and taxonomy terms in Drupal, which are converted to RDF
-and pushed into a Fedora repository. It allows you to configure derivatives, automatic processes that transform files to other types for display or preservation, or extract additional metadata.
-
-## Installation
+Islandora 8 integrates [Drupal](https://www.drupal.org/) (currently, Drupal 8) and Duraspace's [Fedora Repository](https://wiki.duraspace.org/display/FF/Fedora+Repository+Home) project (currently, Fedora 5).
 
-Islandora CLAW is installed through an Ansible Playbook called [claw-playbook](https://github.com/Islandora-Devops/claw-playbook).
-With Git, Vagrant, and Ansible installed, you can spin up a local development environment with
-```bash
-git clone https://github.com/Islandora-Devops/claw-playbook
-cd claw-playbook
-vagrant up
-```
-See the Installation section for more information.
+Islandora 8 allows you to create nodes, media, files, and taxonomy terms in Drupal, which are converted to RDF
+and pushed into a Fedora repository. It also allows you to connect repository content with microservices, small webapps that transform files to other types for display or preservation, or to extract additional metadata.
diff --git a/docs/installation.md b/docs/installation.md
@@ -0,0 +1,8 @@
+Islandora 8 is installed through an Ansible Playbook called [claw-playbook](https://github.com/Islandora-Devops/claw-playbook).
+With Git, Vagrant, and Ansible installed, you can spin up a local development environment with
+```bash
+git clone https://github.com/Islandora-Devops/claw-playbook
+cd claw-playbook
+vagrant up
+```
+See the claw-playbook README for more information.
diff --git a/docs/islandora/README.md b/docs/islandora/README.md
diff --git a/docs/jsonld/README.md b/docs/jsonld/README.md
diff --git a/docs/syn/README.md b/docs/syn/README.md
diff --git a/docs/technical-documentation/migrate-7x.md b/docs/technical-documentation/migrate-7x.md
@@ -0,0 +1,3 @@
+<iframe width="560" height="315" src="https://www.youtube.com/embed/fEDzfSPjKEo" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+For tools to migrate into Islandora 8 from an existing Islandora 7 instance, please see [migrate_7x_claw](https://github.com/Islandora-devops/migrate_7x_claw)
diff --git a/docs/technical-documentation/migrate-csv.md b/docs/technical-documentation/migrate-csv.md
@@ -0,0 +1 @@
+For a full tutorial on migrating from CSV, including sample content, please see [migrate_islandora_csv](https://github.com/Islandora-CLAW/migrate_islandora_csv)
diff --git a/docs/technical-documentation/testing-notes.md b/docs/technical-documentation/testing-notes.md
@@ -1,16 +1,24 @@
-## How to look up a [Gemini](https://github.com/Islandora-CLAW/Crayfish/tree/master/Gemini) entry for a node?
-To locate a particular Gemini entry for a node, you need to know the uuid of the node. You can get the uuid for the node by looking at the devel tab in Drupal or you can get it from json representation: `http://localhost:8000/node/2?_format=json`.  
+## How to look up a Gemini entry for a node?
 
-You can look up Gemini entries for node  using the Gemini service via curl or a REST client such as POSTman. 
+Gemini is a service that maps Drupal URIs to their corresponding Fedora URIs. Each entry is keyed on the UUID assigned by Drupal. 
+
+To get the UUID of a node, taxonomy term, or media entity (see Note below) in Drupal, you can look in the Devel tab or in the JSON representation, e.g.: `http://localhost:8000/node/2?_format=json`.  
+
+Then, you can look up the entry for that UUID using the Gemini service. It's a REST interface, so you can use a REST client such as POSTman, or a command-line tool such as `curl`: 
 
 ```
-curl -H "Authorization:Bearer islandora" http://localhost:8000/gemini/uuid_value
+curl -H "Authorization:Bearer islandora" http://localhost:8000/gemini/[uuid_value]
 ```
 
-Alternatively, you can login to MySQL database, select the gemini database and issue the following query:
+Alternatively, you can login to your SQL database, choose the gemini database, and issue the following query:
+
 `
 select * from Gemini where uuid="uuid_value";
 `
 
+Note: Media objects for files in Fedora aren't indexed in Gemini because they are not reliable. See [Github Issue #1079](https://github.com/Islandora-CLAW/CLAW/issues/1079).
+
 ## How to look up a file metadata in Fedora?
-Files in Fedora have the file URI in Gemini. However, Media for files in Fedora aren't indexed in Gemini because they are not reliable. To look up file metadata, go to `file_uri + /fcr:metadata`.
+Files in Fedora have their file URIs in Gemini. To see file metadata in Fedora, go to `file_uri + /fcr:metadata`. 
+
+For more information about the Gemini service, see the [Gemini README](https://github.com/Islandora-CLAW/Crayfish/tree/master/Gemini).
diff --git a/docs/user-documentation/add-member-to-collection.md b/docs/user-documentation/add-member-to-collection.md
diff --git a/docs/user-documentation/collections.md b/docs/user-documentation/collections.md
@@ -1,7 +1,68 @@
-!!! todo
-    * You might want to use collections to organize, describe, and help with navigation.
-    * A collection is just another node
-    * All nodes can be members of other nodes.
-    * You can edit a node’s Member relationships in…
-    * If you remove something from a collection does it get deleted?
-    * The ‘everything is a collection’ setting is is configurable, but where?
+Collections are groups of repository content that can be described themselves. Repository content is aggregated in a collection by setting the `field_member_of`
+entity reference field to point to a collection. Generally speaking, anything can behave as a collection, and anything with `field_member_of` can be a member of a collection.
+However, collections are 'officially' designated as such by applying the "Collection" taxonomy term to an item's `field_model` field.  By default, Islandora 8 has a context configured to handle collections by looking for that term.
+
+!!! Tip "Collections and Deleting"
+    Collections and their members are
+    independent of each other, and removing something from a collection does not delete it.  **Similarly, deleting a
+    collection does not delete its members.**
+
+## Creating a Collection
+
+From the front page, click on Add content. This is under Tools.
+
+![Click on add content, under tools](../assets/add-content-collection.jpg)
+
+Then click on 'Repository Item' to give your collection the default metadata profile for Islandora 8.
+
+![Click on Repository Item](../assets/repository-item-collection.jpg)
+
+Fill out the form.
+
+Near the end of the form, under System, select Collection from the Model drop down list.
+
+![Near end of form, under System, select collection](../assets/system-collection.jpg) 
+
+Click Save when done.
+
+![The collection has been created. Now let's add some members to this collection.](../assets/collection-parent-node.jpg)
+
+The collection has been created. Now let's add some members to this collection.
+
+## Add Existing Items to a Collection
+
+To populate a collection with existing items, return to any existing content and click on its Edit tab. This brings up the form for this item.
+
+![To populate a collection with existing items, return to any existing content and click on its Edit tab.](../assets/edit-photo-collection.jpg)
+
+Scroll down to the bottom and the System section. In the Member of section, start typing in the name of the collection this item should belong to. Select the name of the collection 
+you want from the autocomplete.
+
+![Scroll down to the bottom and the System section. In the Member of section, start typing in the name of the collection this item should belong to.](../assets/member-of-collection.jpg)
+
+The correct collection is now selected.  Click Save when ready.
+
+![The correct collection is now selected. Click Save when ready.](../assets/member-of-collection-selected.jpg)
+
+To confirm, return to the collection and verify the new item appears in the collection's 'Members' block.
+
+![To confirm, return to the collection and verify the new item appears in the collection's 'Members' block.](../assets/snowfall-collection.jpg)
+
+## Add a New Item as a Member of a Collection
+
+To create an item and add it as a member to a collection in one step, visit a collection and click on its `Members` tab. From the
+`Members` tab, you can manage the members of a collection and perform actions on them.
+
+![From the 'Members' tab, you can manage the members of a collection and perform bulk operations on them.](../assets/members-tab.png)
+
+Click on the `+Add member` button, and then select 'Repository Item' to give your new item a Content Type.  Only content types that
+have the `field_member_of` field will be available from this list.
+
+![Click on the '+Add member' button, and then select 'Repository Item' to give your new item a Content Type.](../assets/select-content-type-for-new-member.png)
+
+You are taken to the creation form for a Repository Item, but if you scroll down to the `System` section, you should see the widget
+for 'Member Of' is already filled out for you with the appropriate collection.
+
+![You should see the widget for 'Member Of' is already filled out for you with the appropriate collection.](../assets/member-of-collection-selected.jpg)
+
+Click 'Save' at the end of the form to create the new item and add it as a member to the collection.
diff --git a/docs/user-documentation/content_types.md b/docs/user-documentation/content_types.md
@@ -1,8 +1,10 @@
 # Create / Update a Content Type
 
-!!! tip The screenshots and pre-existing data in this documentation assume that you are using the [Islandora Demo](https://github.com/Islandora-CLAW/islandora_demo) configuration.
+!!! info
+    The screenshots and pre-existing data in this documentation assume that you are using the [Islandora Demo](https://github.com/Islandora-CLAW/islandora_demo) configuration.
 
-!!! tip This page will address how to create and modify ingest forms (or rather, content types) via the GUI. For help working with forms via the API, please check out the [Further Reading](#further-reading) section for links to more advanced Drupal documentation.
+!!! info
+    This page will address how to create and modify ingest forms (or rather, content types) via the GUI. For help working with forms via the API, please check out the [Further Reading](#further-reading) section for links to more advanced Drupal documentation.
 
 Since objects in Islandora 8 are stored in Drupal as Nodes, we use the standard Drupal Content Types system to create and edit our ‘ingest forms’ [Content Types in Drupal 8](https://www.drupal.org/docs/8/administering-drupal-8-site/managing-content-0/working-with-content-types-and-fields). Islandora 8 forms are Drupal forms, and if you are already familiar with Drupal Field UI, you’re already well equipped to create and modify your own ingest forms in Islandora 8.
 
@@ -12,7 +14,7 @@ This page will address how to create and modify ingest forms (or rather, content
 
 If you have deployed your Islandora 8 with the Islandora Demo configuration, you will already have a Repository Item content type available, with pre-configured fields. In the Admin menu, go to Structure >> Content Types and find the Repository Item content type. Select *Manage Fields*.
 
-![a screenshot of the Add Content Type page](/docs/assets/islandora8_managefields.png)
+![a screenshot of the Add Content Type page](../assets/islandora8_managefields.png)
 
 You will see a list of the fields that are already available in the *Repository Item* content type.
 
@@ -28,21 +30,24 @@ Let’s add a new field where a user can indicate if the repository item needs t
 1. Then configure how the field is described (including its display label and the help text for when it appears on a form) and constraints on its use. In this case, the field will be required for this Content Type, and will be set to “on” by default. In the "Default Value" section, click the checkbox next to "Needs Review" to indicate all new repository items need review by default.
 1. Click "Save settings."
 
-![a screenshot of the field settings page](/docs/assets/islandora8_fieldsettings.png)
+![a screenshot of the field settings page](../assets/islandora8_fieldsettings.png)
 
 The new field has been added:
 
-![a screenshot of a "Needs Review?" field in the Drupal field UI](/docs/assets/islandora8_newfield.png)
+![a screenshot of a "Needs Review?" field in the Drupal field UI](../assets/islandora8_newfield.png)
 
 And it appears in the ingest form when we try to create a new repository object. To test this, go to Content >> Add content >> Repository item:
 
-![a screenshot of a "Needs Review?" field appearing at the bottom of a new node form](/docs/assets/islandora8_newfieldinform.png)
+![a screenshot of a "Needs Review?" field appearing at the bottom of a new node form](../assets/islandora8_newfieldinform.png)
 
-!!! tip New fields, with the exception of Typed Relation fields, are not automatically indexed in Fedora and the triple-store. Update the Content Type's RDF Mapping to enable indexing the field (see below).
+!!! tip "RDF Mappings"
+    New fields, with the exception of Typed Relation fields, are not automatically indexed in Fedora and the triple-store. Update the Content Type's RDF Mapping to enable indexing the field (see below).
 
-!!! tip New fields will not automatically be searchable. They need to be added to the SOLR index configuration. See the ['Setup and Configure Search'](searching.md) page for more information.
+!!! tip "Search"
+    New fields will not automatically be searchable. They need to be added to the SOLR index configuration. See the ['Setup and Configure Search'](searching.md) page for more information.
 
-!!! tip To add new behavior based on the results of this new field, check out [link to Context docs](docs/user-documentation/searching.md)
+!!! tip "Context"
+    To add new behavior based on the results of this new field, check out [link to Context docs](searching.md)
 
 ### Change the Form Display
 
@@ -57,7 +62,7 @@ When creating a new Repository Item, the new field appears at the top, as a set
 
 Finally, let’s change how the results of this field are displayed. Initially the new field shows up at the bottom of repository object pages:
 
-![a screenshot of a "Needs Review?" field in the node display](/docs/assets/islandora8_fieldindisplay.png)
+![a screenshot of a "Needs Review?" field in the node display](../assets/islandora8_fieldindisplay.png)
 
 In the Admin menu, return to Structure > Content Types and find the Repository Item content type again. Select Manage display from the dropdown menu.
 

diff --git a/docs/user-documentation/create-collection.md b/docs/user-documentation/create-collection.md
diff --git a/docs/user-documentation/creating-an-object.md b/docs/user-documentation/creating-an-object.md
@@ -0,0 +1,50 @@
+To create a new item in your Islandora 8 digital repository, we start by creating a node.
+A node holds the descriptive metadata for content, as well as grouping together an original file and
+all of the derivatives files generated from it. To create a new node, click on Add content.
+This is under Tools.
+
+![Click on add content](../assets/add-content-loading-media.jpg)
+
+Then click on Repository Item. This will assign the default metadata profile to your item.
+
+![Click on repository item](../assets/repository-item.jpg)
+
+Fill out the form. We're going to create an image, so under System, select "Image" from the "Model"
+drop down box. Selecting different models will impact how Islandora handles content, dictating
+important behaviours such as display and derivative generation.
+
+![Under system select appropriate model, or format](../assets/under-system-select-format.jpg)
+
+When done, click Save.
+
+## Upload an Original File
+
+Congratulations, you have created a Node! But alas, it has no files.  To upload a file, click on the
+node's Media tab.
+
+![When done, click on Media](../assets/click-media.jpg)
+
+Then click on Add Media (a blue button).
+
+![Click on Add Media](../assets/add-media.jpg)
+
+We want to add an image, so clicking on "Image" is appropriate in most circumstances. Drupal considers
+any type of image that can be viewed natively in the browser as an "Image".  For other image types that
+require special viewers, such as Tiffs, you have to choose "File"
+
+![Click on image option](../assets/image-option.png)
+
+You are now presented with the form for the technical metadata of the file.  There are three required
+parts of the form:
+
+1. The media's name.
+1. The file to upload.
+1. The usage of the file, which dictates how Islandora interprets the file. To trigger derivative
+generation, select "Original File" from the drop down box.
+
+![You are now presented with the form for the technical metadata of the file.](../assets/adding-image.jpg)
+
+Click save when done, and the file will be uploaded (to Fedora by default).  Now return to the node
+you created and you should see the image along with its descriptive metadata.
+
+![The file is now loaded, return to the main site to view](../assets/final-loaded-image.jpg)