"1.x to CLAW" explanatory document

[bryjbrown]

There's a huge conceptual leap between Islandora 1.x and CLAW. 1.x folks have lots of experience with the Fedora 3 way of thinking (cmodels, datastreams, solution packs, etc) but often hit a huge roadblock when they try to frame their ideas for CLAW using 1.x vocabulary and may feel discouraged.

In order to minimize discouragement and empower 1.x users to join the CLAW discussion, it would be great if there were some documentation that explained how CLAW works in terms of 1.x concepts.

Since I'm bringing this up, I'm happy to take the lead on it. This ticket will be used to keep track of progress and questions that come up along the way.

[bryjbrown]

Here's a review of the existing documentation mentioned in the Jan. 25 CLAW call.

• CLAW for 1.x Users
  • This is great! Pretty much exactly the idea I had in mind, but could be taken further. Seems like the most obvious point of entry.
  • I would love to get started on this, but I want to make sure that it is accurate. Can someone review the section about datastreams and verify that it is correct? It refers to "RDF datastreams" and "binary datastreams" in CLAW, whereas I thought Fedora 4 did away with the concept of datastreams entirely.
• Intro to CLAW
  • Also great. An explanation of how CLAW works is a completely different thing from mapping 1.x concepts to new CLAW concepts, so I can see the 2xfor1x page linking to this for further details of certain topics.
  • Since it looks like this was last updated 6 months ago, and can someone verify that this info is still accurate?
• Fedora 4 Glossary
  • Super helpful, and probably something that the previous two pages could link to/quote liberally.
• Fedora 3 to 4 Data Models
  • Probably safe to ignore. Hasn't been updated in almost a year, and only has information on 1.x Islandora data models. I doubt there will be any way to add to this page until the dust settles on CLAW's implementation of data models.

So, path forward:

1. @Islandora-CLAW/committers verify that info in 2xfor1x and Intro to CLAW are still accurate
2. @Islandora-CLAW/committers verify that CLAW/docs is still a future-safe place to write up this documentation (will the primary CLAW repo stay as-is for the foreseeable future, or are there plans to atomize it)?
3. @bryjbrown will propose ways to reorganize and add info to optimize its usefulness for 1.x users and discuss at future CLAW calls

If anyone has an issue or suggestion with this plan, let me know and we can discuss it here.

[DiegoPino]

@bryjbrown++ 😄 will review your proposal, but looks pretty good and totally needed.

[whikloj]

I'll take a look at the 2xfor1x doc and submit a PR with any revisions I can think of.

[ruebot]

verify that CLAW/docs is still a future-safe place to write up this documentation (will the primary CLAW repo stay as-is for the foreseeable future, or are there plans to atomize it)?

That's the place it'll live for the foreseeable future.

[ruebot]

@bryjbrown checking in on this one. How are things going?

[bryjbrown]

@ruebot I got wrapped up in working on bugfixes for the 1.9 release and this fell off my radar, apologies.

It looks like the ecosystem section of the "Intro to CLAW" doc will need some major rewriting since it looks like we've ditched Chullo/Crayfish/PDX. TBH I don't understand the current architecture, I had an okay idea when we were still using Chullo and Crayfish but it looks like theres been some churn since then (my bad for missing the tech calls). Perhaps I could have a Skype session with someone to get a 10,000 ft view of the new architecture and write it up?

Another thing that I think could be added to the list of documents is an "Intro to CLAW Development" doc where we discuss the most efficient way to dive into CLAW work (use the Vagrant VM) along with a very brief overview of the tools used (Composer/Silex/etc) and links to reference documentation for each tool (basically an expanded version of whats at the bottom of the CLAW wiki front page(Developer Resources).

Some sort of "Intro to CLAW RDF" would be extremely helpful as well. In my experience the Semantic Web parts of CLAW work are the biggest hurdles to overcome and semweb is such a huge topic that its hard to know whats relevant for CLAW work and what isn't. I think some sort of document that explains semweb stuff IN THE CONTEXT OF CLAW would be great and could get people up to speed on the relevant aspects of RDF much faster than if you just leave it to them.

I know what I just said sounds like a lot of work, but I think these resources could make newcomers feel less intimidated by what is, to outsiders, an incredibly intimidating stack. I'm all for writing this stuff up, but it will probably require a few bull sessions with some (patient) CLAW devs.

[bryjbrown]

It looks like the Hacking on Islandora CLAW doc could be a great starting point (or thing referenced by) an "Intro to CLAW Development" doc.

[dannylamb]

@bryjbrown You wanna set up a call sometime soon? I can help give you that 10,000 ft view. Feel free to hunt me down in IRC or Skype.

[bryjbrown]

@dannylamb Sure! Would you be available after this week's tech call (March 15)? I'd also be available after Thursday's release call and Friday's roadmap call.

[dannylamb]

@bryjbrown I'm available right after the tech call. See you then.

[ruebot]

@bryjbrown how you doing here? Things going well after the call with @dannylamb?

[bryjbrown]

@ruebot Yep, @dannylamb set me straight on how things are now. I'm now on the Islandoracon Hackfest planning committee, and all the Hackfest project ideas have to do with CLAW. Having these documents ready before the Hackfest would be a major boon to all the folks who aren't familiar with CLAW but want to pitch in, so I'm setting a deadline for myself of May 1st so we have plenty of time to review and share the docs before the Hackfest.

This week's call is going to have a lot of stuff about the Hackfest, so I added an agenda item there to talk about my plans going forward. I'm considering completion of these documents to be part of the Hackfest preparation.

[ruebot]

@bryjbrown that's great, and a fantastic idea! Don't hesitate to reach out of @dannylamb or I in irc if you need anything.

[bryjbrown]

With #616 getting merged, I'd say this particular issue is closeable. @Islandora-CLAW/committers, is it alright for me to kill this one or is there a process to observe?