search

fcrepo4-labs / fcrepo-api-x

Fedora API Extension Framework
Apache License 2.0
10 stars 11 forks source link

Create API-X high level introductory video #88

Closed rduerr closed 7 years ago

rduerr commented 7 years ago

This should be based on the documentation provided; but scripted to demonstrate to repository managers and other management types why API-X is something they should care about and support (i.e., to describe what it can buy them).

rduerr commented 7 years ago

Karen, here are my comments on the draft video:

  1. I love the animations, though there are some fiddly bits to fix up
  2. I think it is odd to keep jumping back and forth between Fedora things and then API-X things. It might be better to get all the Fedora stuff in first, then jump to the API-X stuff
  3. It should be "Fedora [...] a flexible, modular, open source, digital repository". That word digital is important here
  4. The What is Fedora bit should be immediately followed by something that depicts that it is installed in over 300 places and that there are a whole host of different kinds of entities where it is installed (academic and cultural heritage organizations, universities, research institutions, university libraries, national libraries, and government agencies is the list at fedorarepository.org/about). Another point to make is that it handles "very large and complex digital collections of historic and cultural materials as well as scientific data" (from the same web site). Obviously visual representations are better than just words....
  5. When you do get to the API-X stuff you might take a look at the overview section of the page at https://wiki.duraspace.org/display/FF/Design+-+API+Extension+Architecture to get an idea of what kinds of examples to talk about when you get to the non-core stuff later on.
  6. I like how the Standard Fedora API animation is juxtaposed with the Fedora with API-X animation (minutes 0:27 - 1:00) and suggest moving the Fedora core functionality bits before those two animations.
  7. It seemed odd that only the CRUD, versioning, and authorization interactions were depicted for the core functionality section. Some reason why (showing a few examples only?) for that should be made so that people don't wonder. Maybe just adding the word "examples" to the header would be sufficient?
  8. At 1:06 it should say "As a digital repository, Fedora's API supports a set of core functionality..."
  9. At 0:45 the text at the bottom of the diagram starts off OK; but the ending needs to change. It currently ends in "...opportunity to change the package or the route"; but this audience likely isn't going to understand either concept (though the animation helps here) - I couldn't really come up with anything better though (thinking about something like translating requests/results and performing external tasks or something like that)...
  10. On that same animation, make sure the arrow back to the client doesn't start until the external gear arrows come back in to API-X.
  11. A storyboard would help visualize all of this... Maybe we should talk on Monday...
karenhanson commented 7 years ago

Here is an updated version: https://www.youtube.com/watch?v=dOGpHpP_WcA Things that I suspect need more work... 1) The wording on the "how it works" bit, which you mentioned above (#9). Still needs to be clearer and needs to represent that intercepting services don't necessarily modify the request and that there may be more than one. 2) I added the other features of core Fedora API, maybe it's too much now I can cut it any way you like!
3) Input on coverage / accuracy would be helpful - I think maybe I need to mention Linked Data Platform somewhere at the start. 4) Perhaps there is a better way to go through the examples - drawing a blank on how to animate that. 5) Some of the transitions are rough - I will fix them when we're done rearranging things as they break when I move things. 6) Need some info to put at the end e.g. a contact, a website, instructions how to learn more.

awoods commented 7 years ago

This is great @karenhanson. Two initial comments:

  1. There is one more core Fedora service: Batch Atomic Operations
  2. Typo: geospacial -> geospatial

Even if we end up cutting some of the core Fedora services from this video, I would like to keep the segments for other videos. You have done a great job of depicting them in intelligible ways.

htpvu commented 7 years ago

@fcrepo4-labs/fcrepo-api-x-dev, Could all who are interested in reviewing and commenting on the video do so before next Monday? @karenhanson posted an updated version last week. She'll start working on the final version next week. https://www.youtube.com/watch?v=dOGpHpP_WcA

rduerr commented 7 years ago

@karenhanson - This is great already! I’d like to show it to my ELOKA team even in its current state. Would you mind if I did that? By the way the examples of what can be done with API-X are perfect - now we just need to get folks to implement them….

On Nov 28, 2016, at 11:13 AM, Hanh Vu notifications@github.com wrote:

@fcrepo4-labs/fcrepo-api-x-dev, Could all who are interested in reviewing and commenting on the video do so before next Monday? @karenhanson https://github.com/karenhanson posted an updated version last week. She'll start working on the final version next week. https://www.youtube.com/watch?v=dOGpHpP_WcA https://www.youtube.com/watch?v=dOGpHpP_WcA — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/fcrepo4-labs/fcrepo-api-x/issues/88#issuecomment-263348008, or mute the thread https://github.com/notifications/unsubscribe-auth/ABeSvDTE9GYKYaQThGVDbYpjhY459kMjks5rCxmsgaJpZM4KvaZh.

karenhanson commented 7 years ago

@rduerr yes, please feel free to show the rough version - I welcome any feedback from the ELOKA team as well! The link will change when we load the final polished version, so we should wait to share the link more broadly. At minimum I will need to correct the two things mentioned by @awoods, add some contact info at the end, and polish up the transitions.

jwestgard commented 7 years ago

Thanks for putting this together. It looks great! I noticed a typo at 2:35 (should be geospatial), and I also think it might be better to say, rather than "expose IIIF-compatible views of images", something like "enable IIIF services for image data". This seems more accurate for how API-X will likely be used, namely as the glue connecting Fedora to a IIIF compliant image server. Apologies if this seems like hair-splitting...

karenhanson commented 7 years ago

Here is an updated version that includes everyone's feedback. Please let me know if I need to change anything else before I polish the timing and transitions and publish the final version. Thanks! https://www.youtube.com/watch?v=gACfN4wXGOw

jwestgard commented 7 years ago

@karenhanson: I think it looks great. I particularly like the section detailing the various domains and how they might use API-X -- that seems like it will be very effective in communicating the importance of this work to the wider world.

karenhanson commented 7 years ago

Here is the final public link: https://www.youtube.com/watch?v=4BgnbMlzYUM MP4 available here: https://drive.google.com/open?id=0B9klf6ZJ3Q3lXzc2aHJNUEd6clU Thank you all for your input!