Documentation: Migrate docs from Islandoracon hack/doc

[kimpham54]

We should do something with the Islandora hack/doc CLAW documentation. Lots of good stuff here: https://docs.google.com/document/d/1CN7mBYdU-ACYoDwWFncUwLPD2bLpt2FKG9CuT63_Pps/edit#heading=h.ptidptu8k2h

[ysuarez]

I would like to volunteer to format the documentation in the Google Doc into Markdown. Of course others might want to work on this too, and I would love to work with anyone too. Additionally, there are still some comments in the Google Doc discussing how to best write parts of the docs. So there might be a need for a final decision on how to resolve any of those debates. Perhaps we can start with the sections that do not have comments for now.

I also want to try to create a PR with the changes, so that it gets included in the CLAW repo. I have a fork of the CLAW repo already. I can start some of the formatting and report back.

Finally, there needs to be a decision on where to put the content within the CLAW repo (and Github IO site), assuming that is where the content should be put according to the community/docs group. Off the top of my head, my suggestion would be to put this new content here...

docs/user-documentation (http://islandora-claw.github.io/CLAW/user-documentation/)

just like docs/user-documentation/intro-to-claw.md
(http://islandora-claw.github.io/CLAW/user-documentation/intro-to-claw/)

though that is only a suggestion.

Thoughts?

Thanks, Yamil

[kimpham54]

@ysuarez happy to work with you as well. I can also help with proofreading, testing, and diagramming. I'll add the ticket to this Wednesday's CLAW call https://github.com/Islandora-CLAW/CLAW/wiki/May-24%2C-2017 if you'd like to bring up your proposal there and see what people think.

[whikloj]

Sounds great @ysuarez & @kimpham54. I was just trying to find the Google Doc link. This is super fortuitous.

[ysuarez]

Here is an update for today's (2017-05-24) CLAW call...

I have been working on how to best format the Google Doc into MarkDown. Here is a list of the questions I have for the community, I want to list them here for some early feedback before I make a bunch of PRs.

• What should this document be called when added to CLAW site, currently it is called “Behold CLAW”?

• Should it be broken down into multiple .md file or keep it as a single document?

• I was considering creating a subfolder for images and other media inside of /doc? I was thinking of using a generic term like “media”, but I am open to suggestions for a folder name

• I would like to create a table of contents for this documentation content, specially if it remains as a single “file.” Though it so far appears that MarkDown does not usually provide automatic TOC creation

• What to do about localized “draft” content and/or localized content with attached comments debating what the final content should be. There are comments that more or less say something like “find a better link” if I recall correctly. Iw oddly like some input on how well all make the final decision on what to format/upload.

• Also I am still struggling with setting up a github.io live preview of the MarkDown content from fork of the CLAW repo. So I may follow up with community requests for advice on how to set github.io up so I can share previews of the work I have done before putting in a PR.

• Finally, here is a sloppy commit from my CLAW repo fork showing my first attempt at updating the repo to have a link in the global navigation to "Behold Claw" and my attempts to start formatting a manual TOC and formatting some of the Google Doc content. https://github.com/ysuarez/CLAW/commit/73566a69c9b1e81e3c67383e31105a1bacf124e4

Thanks, Yamil

[whikloj]

Hey @ysuarez, my thoughts inline

What should this document be called when added to CLAW site, currently it is called “Behold CLAW”?

I'm not sure, but this can be changed. Once you have it in Markdown we can try to get some more input around this.

Should it be broken down into multiple .md file or keep it as a single document?

I think you'll probably need to use more than one file for this. Especially as there is a variety of topics convered.

I was considering creating a subfolder for images and other media inside of /doc? I was thinking of using a generic term like “media”, but I am open to suggestions for a folder name

This is a fine name and I have no issue with that.

Alternatively you can:

1. Create a new comment anywhere in Github, like your own repo.
2. Drag/drop the image into a comment.
3. Github uploads the image and if you then edit the comment you can copy the link to the image.
4. The image persists even if you delete the original comment.

But either works.

I would like to create a table of contents for this documentation content, specially if it remains as a single “file.” Though it so far appears that MarkDown does not usually provide automatic TOC creation

Yeah Github doesn't seem to have an automatic TOC function. So you have to make it manually. There are anchors added at every heading, the anchors are

1. The text of the heading.
2. All lowercase.
3. With hyphens (-) for spaces.
4. With all non-alphanumeric characters (a-z & 0-9) removed.

So a heading of 2012. It was best of times. It was the blurst of times! becomes 2012-it-was-the-best-of-times-it-was-the-blurst-of-times

And you just create a link using # and your anchor value. [This is the link text](#2012-it-was-the-best-of-times-it-was-the-blurst-of-times)

What to do about localized “draft” content and/or localized content with attached comments debating what the final content should be. There are comments that more or less say something like “find a better link” if I recall correctly. Iw oddly like some input on how well all make the final decision on what to format/upload.

That is a good question. Probably best to just add some sort of TODO to those items so we remember to go back and fix them.

Also I am still struggling with setting up a github.io live preview of the MarkDown content from fork of the CLAW repo. So I may follow up with community requests for advice on how to set github.io up so I can share previews of the work I have done before putting in a PR.

@ruebot is your huckleberry when it comes to MkDocs

Finally, here is a sloppy commit from my CLAW repo fork showing my first attempt at updating the repo to have a link in the global navigation to "Behold Claw" and my attempts to start formatting a manual TOC and formatting some of the Google Doc content. ysuarez/CLAW@73566a6

Looking good, you'll need to add a space between your ### and the words that follow to get the correct formatting. But its coming along well. 👍

[ruebot]

@ysuarez

What should this document be called when added to CLAW site, currently it is called “Behold CLAW”?

See answer to next question.

Should it be broken down into multiple .md file or keep it as a single document?

It should be broken up into multiple docs, and fall under the existing categories setup; User Documentation or Technical Documentation. If it doesn't fall under one of those, we'll need to discuss a new category. The categories are outlined in the MkDocs configuration file.

I was considering creating a subfolder for images and other media inside of /doc? I was thinking of using a generic term like “media”, but I am open to suggestions for a folder name

Such a folder already exists here.

I would like to create a table of contents for this documentation content, specially if it remains as a single “file.” Though it so far appears that MarkDown does not usually provide automatic TOC creation

See mention of MkDocs configuration file above.

What to do about localized “draft” content and/or localized content with attached comments debating what the final content should be. There are comments that more or less say something like “find a better link” if I recall correctly. Iw oddly like some input on how well all make the final decision on what to format/upload.

This is can be settled before pull requests are made, or during pull requests. This will definitely need to be split up into multiple pull requests.

Also I am still struggling with setting up a github.io live preview of the MarkDown content from fork of the CLAW repo. So I may follow up with community requests for advice on how to set github.io up so I can share previews of the work I have done before putting in a PR.

Please see "How to build documentation." MkDocs provides the ability to build locally and preview what the documentation site will look like.

Finally, here is a sloppy commit from my CLAW repo fork showing my first attempt at updating the repo to have a link in the global navigation to "Behold Claw" and my attempts to start formatting a manual TOC and formatting some of the Google Doc content.

Before you make a pull request, you'll want to have a signed CLA. More info here.

[ysuarez]

First of all, thanks for all the feedback!

I just added PR #650 as my first ever PR for the Islandora project. Apologies and thanks in advance for any corrections or feedback, if I did not follow the process correctly.

I decided to grab some content from a section in the Google Doc called "system navigation," but I renamed it 'Getting Started with Islandora CLAW.' I placed the content under the existing 'User documentation' section in the global navigation. I'll await some feedback before I start formatting more content from the Google Doc.

On the topic of creating a table of contents, the MkDocs framework or the MkDocs theme we picked automatically creates a TOC. So we are good on that front.

@ruebot Thanks for pointing out the assets/, I totally missed that last time.

@ruebot Also, when I mentioned I was having issues previewing my changes I should have been more clear. I was referring to hosting my (documentation) changes for the outside world off of the Github web servers using content from my fork of the CLAW repo hosted. At the conference I was able to set up MkDocs on my laptop without issue. Sadly I have been getting errors on the Github site when trying to visit my CLAW repo fork on the Github web servers. For example, the URL https://ysuarez.github.io/CLAW/ gives me 404 errors.

If I look at the settings for my fork of the CLAW repo, the error I got was: "Your site is having problems building: The submodule registered for ./Crayfish could not be cloned. Make sure it's using https:// and that it's a public repo. For more information, see https://help.github.com/articles/page-build-failed-invalid-submodule/."

I can just stick to PRs, but I thought it could help others that are not very familiar with RAW MarkDown, to make it a lot easier to evaluate my documentation changes on a fully rendered MkDocs version of the content/site if I could point them to a Github hosted URL like https://ysuarez.github.io/CLAW/

Again, not a big deal, just wanted to share what I ran into.

Finally, 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.

[dannylamb]

@ysuarez Seems like there was a hiccup. I'm not seeing a CLA delivered to community@islandora.ca on that date. Can you try resending it?

[dannylamb]

Ha! It got caught in community@islandora.ca's spam filters, nestled between several exciting opportunities to sell wedding shoes.

We've got it, and from a legal standpoint you are good to go for contributions. @ysuarez++

[ysuarez]

@dannylamb thanks!

[ysuarez]

Quick update, since Issue #643 was closed (Use Nodes instead of our custom FedoraResource entity), I added a new commit to PR #650 to reflect the use of nodes in the "Getting Started with Islandora CLAW" section. Currently waiting for feedback.

[ysuarez]

One more update, @dwk2 sent me a link to this repo for a project called gdocs2md that provides the code for Google Docs custom functions/macros for converting Google Docs to MarkDown. MarkDown is the mark up language of the CLAW docs, so we could try to use this code to speed up the conversion of the document created at the 2017 Islandoracon Hack/doc. The devil is always in the details, but it should be of some help for re-formatting this document or for future Hack/doc or other submissions.

[dannylamb]

@ysuarez It's a bit hazy due to the lengthy upscroll on this issue, but do you feel #650 fully resolves this? In other words, are you comfortable with me closing this issue?

[ysuarez]

@dannylamb there is a lot more content from the 2017 hack/doc Google Doc that could be moved to the CLAW docs. I guess we can close this issue, and then later on create a new issue for coordinating the work on certain parts of the content from the Google Doc.

For example, below are some of the content section titles of what is still left on the Google Doc.

• System Analogies
  • Drupal 8 (drupal-project)
  • Fedora 4
  • Crayfish Microservices
    • Gemini
    • Milliner
    • Houdini
    • Hypercube
  • Alpaca
  • Syn
  • triplestore
• System Navigation
  • How to edit multiple objects
  • How to delete an object
  • How to add an object to multiple collections
  • How to purge/delete objects
  • How to delete a collection and all of its child objects
  • How to batch delete multiple objects
  • How to make mass edits and/or find and replace
  • How to review mapping of Metadata fields in an object

I suspect that some of the content in those sections above may already be outdated because of the switch to Drupal nodes (Issue #643). In addition some of the content was not completely fleshed out due to time constraints, so it would be fine to start with new Github issues later on. Though I saw comments in the Google Doc that the system analogies were done well. I can work with @kimpham54 and others (@uconnjeustis, etc.) to pick new sections to work on as well as what sections to ignore from the Google Doc.

[ysuarez]

@whikloj since you were there at the hack/dock and helped to explain a lot of things that ended up in the Google Doc, do you have any thoughts on how to proceed with this CLAW issue, i.e. should it be closed or kept open? See my thoughts above.

[dannylamb]

@ysuarez How about creating a meta-issue to keep track of everything that you've listed? You can make checklists with the editor or in markdown with - []

See #572 as an example.

[ysuarez]

@dannylamb thanks for telling me about meta-issues and the use of checklists within them, this may be a great time to use both. I still would like to hear what @kimpham54 thinks about how to proceed, since she is the one that created this issue. If folks want to create the meta-issue (with checkboxes), I volunteer to create it. BTW, I could use tips from anyone on how to properly format/write a meta-issue, but it might be as simple as stating that in the first line and then making sure to create and update the checkboxes as progress is made.

[kimpham54]

@ysuarez Yes Feel free to close this issue and create a new issue with the existing documentation tasks. Good job with all of your work!

[ysuarez]

@kimpham54 thanks for your confirmation that you approve of closing this issue.

I will create a new issue for the rest of the content.

@dannylamb go ahead and close the issue. BTW, who can close issues in this context? I suspect the issue creator and those with admin rights in this repo?

[dannylamb]

@ysuarez I've added you as a collaborator to this repo. I'm wondering if that gives you issue closing power. Can you let me know if it doesn't?

[ysuarez]

@dannylamb thanks for adding me as a collaborator. So far I don’t see a "close" UI element here.

[dannylamb]

Whelp, it was worth a shot. I guess it's tied to owners or the user who opened the issue.