Islandora · whikloj · Apr 18, 2019 · Mar 7, 2019 · Mar 7, 2019 · Mar 7, 2019
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,7 +1,3 @@
-# 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.
 
@@ -10,13 +6,3 @@ Islandora CLAW integrates [Drupal](https://www.drupal.org/) (currently, Drupal 8
 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 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.
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/jsonld/README.md b/docs/jsonld/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,23 @@
-## 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 the mysql database, select 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,64 @@
-!!! 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.  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
@@ -42,7 +42,7 @@ And it appears in the ingest form when we try to create a new repository object.
 
 !!! 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 To add new behavior based on the results of this new field, check out [link to Context docs](docs/user-documentation/searching.md)
+!!! tip To add new behavior based on the results of this new field, check out [link to Context docs](searching.md)
 
 ### Change the Form Display
 

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 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)
diff --git a/docs/user-documentation/datastreams.md b/docs/user-documentation/datastreams.md
@@ -1,23 +1,45 @@
-## Media in Islandora 8
+Drupal 8 recognizes files (such as images, audio files, video files, etc.) but wraps each file in an intermediate structure called a
+"media" to allow us to attach fields to files. It is in a media's fields that we store information about the media's file, such as file
+size, width and height (for images), alt text (for images), creation date, and so on.
 
-Islandora 8's equivalent of Islandora 7.x datastreams are "media". Drupal 8 recognizes files (such as images, audio files, video files, etc.) but wraps each file in an intermediate structure called a "media" to allow us to attach fields (including Drupal tags) to files. It is in a media's fields that we store information about the media's file, such as file size, width and height (for images), alt text (for images), creation date, and so on.
+!!! Note
+    In Islandora 7, this sort of technical metadata would have been stored in a single RELS-INT datastream.
+    In Islandora 8, each datastream holds its own technical metadata using media entities.
 
-Just as an Islandora 7.x object can have any number of datastreams, and Islandora 8 object can have any number of media associated with it. Unlike in Islandora 7.x, which used unique datastream IDs to indicate the function of a file ("OBJ", "TN", etc.), Islandora 8 uses Drupal tags from the "Media Use" vocabulary to indicate a file's function. The values for this vocabulary show up in the media edit form like any other Drupal vocabulary:
+## Media Ownership
 
-![Media tab](../assets/media_use_vocabulary_media_form.png)
+Islandora 8 objects can have any number of media associated with them. Media advertise which object they belong to using a special field,
+"Media Of". By editing this field, you can change the what node owns the media, and therefore, where it gets displayed or managed.
+
+!!! Note
+    The direction of the relationship between objects and datastreams is reversed when compared to Islandora 7.  Generally speaking,
+    objects are unaware of their datastreams, and it's a Drupal view that lists datastreams for an object.
+
+## Media Usage
 
-Because the Media Use vocabulary is an ordinary Drupal vocabulary, Islandora 8 site administrators can add their own tags, and in turn, these local tags can be used to identify media that have some custom local purpose. In fact, the Media Use vocabulary has some tags that identify files that have no real use in Islandora 8 but that are migrated from Islandora 7.x. The "Audit Trail", "Collection Policy", "Dublin Core File", "MODS File", and "RELS-EXT File" all fall into this category. These media are attached to an Islandora 8 object during migrations from Islandora 7.x, so that the content you created in Islandora 7.x can be identified after it has been migrated to Islandora 8, despite the differences between the two platforms.
+Islandora 8 media express their intended use with a special "Media Use" field, which accepts taxonomy terms from the "Media Usage"
+vocabulary. Because the Media Usage vocabulary is an ordinary Drupal vocabulary, Islandora 8 site administrators can add their own
+terms, and in turn, these local terms can be used to identify media that have some custom local purpose.
 
-### Derivatives
+![Media tab](../assets/media_use_vocabulary_media_form.png)
 
-Islandora 8 generates derivatives much like Islandora 7 does. Just as Islandora 7.x's derivatives get assigned datastream IDs, Islandora 8's derivatives are assigned values from the Media Use vocabulary. For example, a thumbnail generated from am image is assigned the "Thumbnail image" tag. The derivatives are listed along with the rest of an Islandora 8 object's media, within the "Media" tab in the object:
+!!! Note
+    Terms from the Media Usage vocabulary are very similar to DSIDs in Islandora 7.  The only difference is that a DSID is immutable,
+    but a media's usage can be changed at any time through the media's edit form.
 
-![Media tab](../assets/media_tab.png)
+## Derivatives
 
-For this image, we can see that a "Service File" and a "Thumbnail Image" derivatives have been generated and added to the object's list of media:
+Islandora generates derivatives based on Media Usage for a Media and the Model of the node that owns it.  All of this is configurable
+using context, but by default, derivatives are generated from "Original Files". When an Original File is uploaded, if the node that
+owns it has an "Image" model, image derivatives are created.  If it's a "Video", then video derivatives are generated, etc...
 
 ![Media tab](../assets/islandora_8_derivatives_sample.png)
 
-### Media revisions
+Within an node's media tab, you can see all of its media, including derivatives, listed along with their usage. For example, from the
+Original File, a lower quality "Service File" and a smaller "Thumbnail Image" file were generated.
+
+For more information on how to set configure derivatives, see the section on context.
+
+## Media revisions
 
 To be completed on resolution of https://github.com/Islandora-CLAW/CLAW/issues/1035.