Documentation: new content from hack/doc "Getting Started with Islandora CLAW" #650
Conversation
|
Thanks for this @ysuarez! I'll comment inline on the PR. |
| 11. Revision log message | ||
| 12. Click "Save" button. | ||
| 13. Once you upload a file, you can Edit or Remove it. | ||
|
|
There was a problem hiding this comment.
agreed, it's too stimulating
There was a problem hiding this comment.
My apologies, I totally missed that. Will be on the lookout for these extra spaces going forward.
| ## Administrative Tasks | ||
|
|
||
| ### How to Add an Item to a Collection | ||
| 1. Click the **Manage** tab from the top toolbar. |
There was a problem hiding this comment.
If we have an "How to Add an Item to a Collection", there needs to be a "How to Add a Collection" before it.
There was a problem hiding this comment.
I'll work on this, if someone doesn't get to it before I do. I am still learning CLAW, but I may be able to write out the basics steps by trying it out on my CLAW VM.
| 1. Click the **Manage** tab from the top toolbar. | ||
| 2. Select **People** tab from the resulting menu. | ||
| 3. Click the **Permissions** tab in the set of tabs above the Add User button. | ||
| 4. Click the blue botton “Add role” |
| 3. Select **People** tab from the resulting menu. | ||
|  | ||
| 4. Enter all the required fields, as indicated by red asterisks, in the Add User page. | ||
| 5. Click on “Create New Account” button at the bottom of the page. |
There was a problem hiding this comment.
My apologies, this came from the Google Doc and I missed them. I should have known to look for them, smart quotes have burned me in the past.
| ## How to Add a User | ||
| 1. Log in under admin credentials. | ||
| 2. Click the **Manage** tab from the top toolbar. | ||
| 3. Select **People** tab from the resulting menu. |
There was a problem hiding this comment.
It seems there are inconsistencies with items that are wrapped in quotes, and items that are bolded. Is there a distinct difference?
There was a problem hiding this comment.
I completely agree. I mostly followed what the hack/doc participants had created in the Google Doc, and it had these inconsistencies. I was not suse which practices were preferred, but initially I wanted to just follow what they did until I got feedback from the community/committers.
Is there a community documentation standard I should follow or a place I could look it up? For example, in some docs they format all menu or button labels in a particular style like bold or italics. In the Google Doc sometimes they used bold or sometimes they used quotes. Once I am given guidelines or if I find them on my own, I can reformat what I have done so far as well as continue the practice with the content that is left in the Google Doc. In the meantime, I will look over some of the docs on the Islandora wiki more carefully to see what has been done in the past.
One thing I did change from the original hack/doc content was to enforce the use of the word "click" instead of "select" when the contents referred to clicking a button, tab or link.
| 6. Click the **Save** button. | ||
| 7. To edit the permission for a role, click on the **Edit** dropdown menu to the right of the role and select **Edit Permissions**. | ||
| 8. Scroll down until you see the “Islandora section” of options. (Currently this is the very bottom of a very long page) | ||
| 1. Resource ‘type’ is what you’ll most often deal with |
| 3. RDF is a Fedora resource | ||
| 4. RDF Source (i.e. descriptive information) is a Resource | ||
| 5. Collections are now considered a type | ||
| 6. Audio, Images, etc are also going to be types (this might require changes in the vocabulary we use Drupal “entities” (i.e. your core set of elements) and Drupal “bundles” (includes your entities plus other elements) |
| 1. Log in under admin credentials. | ||
| 2. Click the **Manage** tab from the top toolbar. | ||
| 3. Select **People** tab from the resulting menu. | ||
|  |
There was a problem hiding this comment.
Will there be more screenshots? It seems inconsistent to only have one.
There was a problem hiding this comment.
Good question This is again what the hack/doc document had. I started making some new screenshots, but I wanted to get this feedback first. @kimpham54 this morning already made a PR on my CLAW fork with additional screenshots I will soon include in this PR.
| 4. Click on "Add fedora resource" button. | ||
| 5. Click on "Islandora image" link. This will load the "Create of bundle Islandora image" page. | ||
| 6. Fill out form fields. [NOTE: currently the generation of image derivatives is not supported.] | ||
| 1. Name |
There was a problem hiding this comment.
These sub-items should be bullets, not Roman numerals.
There was a problem hiding this comment.
I agree, but that is how it looked on the Google Doc. I will make the change.
| ### How to Add an Item to a Collection | ||
| 1. Click the **Manage** tab from the top toolbar. | ||
| 2. Select **Content** tab from the resulting menu. | ||
| 3. Click on **Fedora Resources*** tab (3rd tab). |
There was a problem hiding this comment.
One extra asterisk at the end of Fedora Resources.
| 3. memberOf | ||
| 1. This field will auto-populate | ||
| 4. Description | ||
| 5. OJB |
|
👍 Nice work @ysuarez. Great first pass at getting the Google doc into Github, just a couple fixes to make. As for the bold versus "quoted" debate, I would stick with bold for things you click on (like buttons or links). For the title of a page or section, that is up to you. |
…o docs_getting_started_with_islandora_claw
| 1. Name | ||
| 2. Authored by | ||
| 3. memberOf | ||
| 1. This field will auto-populate |
There was a problem hiding this comment.
If sub-items are going to be bullets, then this sub-sub-item should probably also be a bullet. 😃
Related to PR Islandora#650 * removed smart quotes * changed list type to bulleted list
|
@whikloj Thanks for the suggestions on formatting UI labels. I made a note of it for this PR and for future documentation work. I may not have time today to make the changes, but I can work on it later this week. Sadly this may be reason enough to block this PR, and I understand, but I am open to having others create a PR from my forked repo in the meantime. @ruebot thanks again for all the feedback @kimpham54 thanks for your PR |
|
@ysuarez I don't think there is a rush on this. If you want to (and can) keep moving this along, it can sit for now. There are other parts of the original Google Doc that can be picked up by others to either create new documentation or extend the existing docs. |
|
This will need to be updated once #643 lands. Does anybody want to volunteer to help test that PR, and create documentation in the process? |
|
@ruebot (@whikloj @whikloj and to others) I just pushed two new commits to standardize the UI label formatting. I also added a section for "How to Create a Collection." There are still about 10 more "How to" sections in the Hack/doc Google Doc, but many are not as fleshed out as the ones I have formatted so far. I can continue simplifying/editing and formatting the rest in this PR or a separate one, and then await feedback on what content needs to be fixed/updated. For the record, here are the titles of most of remaining sections...
Wondering if some of these sections should be placed in the new 'Getting Started with Islandora CLAW' or should a new page be created? Thoughts? Thanks. |
|
Ideally they would all be sub-sections of "Getting Started with Islandora CLAW". |
| 6. Click the **Save** button. | ||
| 7. To edit the permissions for a role, click on the **Edit** dropdown menu to the right of the role and select **Edit Permissions**. | ||
| 8. Scroll down until you see the *Islandora section* of options. (Currently this is the very bottom of a very long page) | ||
| * Resource ‘type’ is what you’ll most often deal with |
There was a problem hiding this comment.
I'm thinking out loud here, but should we add a screen shot here? Or could that lead us into a 🐰 hole of un-imaginable depth over time?
There was a problem hiding this comment.
@ysuarez Recapping our IRC conversation (starting @ 13:32). The rabbit hole is once more permissions get added, keeping a screenshot of them could be problematic.
However, currently there is only one section of permissions and as this is a Getting Started with Islandora CLAW document, maybe a single screenshot with some permissions is good enough. 🤷♂️
Here is some of the current permissions lines now using Nodes.
There was a problem hiding this comment.
I agree, we can add a basic screenshot with the first couple of rows of relevant CLAW permissions
|
Now that I have figured on that I was confusing Github Issues and Github Pull Requests thanks to @whikloj, I am no longer confused. I will wait for the vagrant build to be ready so I can try out the new functionality an update this pull request. Of course anyone is welcome to contribute too. My understanding so far is that we need to update the sections on:
|
| 6. Click the **Save** button. | ||
| 7. To edit the permissions for a role, click on the **Edit** dropdown menu to the right of the role and select **Edit Permissions**. | ||
| 8. Scroll down until you see the *Node* section of options, until you see options that have an *Islandora* preffix. For example, *Islandora Collection: Create new content*. | ||
| * Resource ‘type’ is what you’ll most often deal with |
There was a problem hiding this comment.
I am not sure if we need lines 23-28. Let me know what you all think.
There was a problem hiding this comment.
Yeah I don't know if that makes sense anymore. I also think it might be overly complex for a "getting started" document.
There was a problem hiding this comment.
@whikloj thanks for the feedback. I took that content out.
…ome leadign spaces
| * I.e. use the course code for a particular class of students working on a particular collection. | ||
| 6. Click the **Save** button. | ||
| 7. To edit the permissions for a role, click on the **Edit** dropdown menu to the right of the role and select **Edit Permissions**. | ||
| 8. Scroll down until you see the *Node* section of options, until you see options that have an *Islandora* preffix. For example, *Islandora Collection: Create new content*. |
There was a problem hiding this comment.
Two little things.
- "Scroll down until you see the Node section of options, until you see the options that have an..."
The language is jumbly. - Typo preffix, should be prefix
|
👋 from 🇬🇧 Carry on 😄 |
|
@whikloj good points. I changed the phrasing to... Let me know if I should make other changes. |
|
@ysuarez++ Thanks for this! |
|
@ysuarez nice work, thanks for carrying it through to the end. 👏 |
GitHub Issue: #632
This is the Google doc created during the 2017 Islandoracon Hack/doc where I got the content from:
https://docs.google.com/document/d/1CN7mBYdU-ACYoDwWFncUwLPD2bLpt2FKG9CuT63_Pps/edit#heading=h.ptidptu8k2h
The older documentation I used as a basic guide:
https://wiki.duraspace.org/display/ISLANDORA/Getting+Started+with+Islandora
https://wiki.duraspace.org/display/ISLANDORA/How+to+Add+an+Item+to+a+Digital+Collection
What does this Pull Request do?
What's new?
How should this be tested?
Please read over to find:
Please add comments on how the documentation should be extended or changed, or add additional PRs with new changes.
Additional Notes:
For the record, I emailed my CLA to the "community" email address on May 20, 2017. Did not get a response, but the CLA should be on file by now.
Interested parties
@Islandora-CLAW/committers
@kimpham54