Recipe 9: Multiple Related Images (Book, etc.)

[glenrobson]

Links

• Original Issue: Book (simplest, > 1 canvas) cookbook-recipes#9
• Pull Request: Recipe #0009 — Simplest Manifest - Multiple Related Images (book, etc.) cookbook-recipes#153
• Preview: https://preview.iiif.io/cookbook/0009-book-1/recipe/0009-book-1/

Background and Summary

This is an example of a simple book modelled as a IIIF manifest. It introduces the reader to a manifest with multiple canvases and gives advice on which properties are important, for example a canvas label. It also briefly introduces behavior which is important for the example but references another recipe to guide readers to more information.

During the development of this recipe there was some discussion on thumbnails and whether to include this in the example. There are a number of ways to do thumbnails in IIIF and support varies between viewers. We decided on balance not to include them in the example but to point strongly to the yet to be written thumbnail recipe. There are two yet to be written recipes on thumbnails which will be important to get completed soon as they will be relied on for future recipes. Issue #16 is for the basic description on how to reference a thumbnail and issue #12 acknowledges the different options and provides advice on how to make the most efficient choice.

A +1 is the recipe is OK to go through to the master
A -1 is that is not OK and a comment in this issue should say what needs to be done

[ahankinson]

The explanation of the recipe in the PR is a bit clearer than in the cookbook itself. “Multiple related images” is quite vague, and could mean many things — eg, related images from different institutions, or secondary images that relate to the main images, such as images of a printed catalogue that describe the images of the manuscript.

The description “ This is an example of a simple book modelled as a IIIF manifest.” as the first sentence would make the purpose of this recipe a whole lot clearer. And given that it’s likely to target a very beginner audience, there is a lot of IIIF-ese that is a bit unfriendly to that audience, such as the sentence “If you have an object consisting of a sequence of multiple related images, this pattern turns it into a valid IIIF Presentation resource“. What’s a presentation resource? Is it different from a Manifest? Are book pages a sequence of multiple related images? What’s the consequence of having an invalid IIIF presentation resource?

Any “etc.” Should either be expanded on or removed, since the target audience does not really have a good indication of how to fill that in.

I won’t -1 this because I seem to be in the minority and don’t want to be a blocker, so I will vote neutral.

[regisrob]

Thanks @ahankinson for your feedback. I agree with most of your reservations.

There was a tension between writing a recipe for 1/ a real world object (yes a book, but what kind? Is it a medieval manuscript? an atlas? a modern printed novel? considering that the resulting Manifest would be quite different in each case), or 2/ a more generic recipe describing a multi-image object like a book, which follows on from the very first recipe of the cookbook Simplest Manifest - Single Image File.
Given the comments in the original issue, I opted for the latter when I started to work on this recipe (so trying to leave out the "real world object" aspect of it).

You are right about the wording: I think it is clearer to simply use Manifest instead of an obscure "Presentation resource", provided the beginner reader has a broad sense of what is a Manifest.
Likewise for the "etc.", I guess we can get rid of them safely!

This recipe may require further discussions and may need to be revised. I'd be happy to do that based on what other people think/suggest.

[ahankinson]

Maybe it comes down to the preconceived notions I have about the cookbook -- I was thinking that I come to it wanting to know how to bake a "Black Forest Chocolate Cake With Icing", and might get a bit confused if the recipe says "Baking a dark round confectionary (e.g., a cake, etc.)" 😄

In other words, making it too generic might be counter-productive since anyone coming to the cookbook wanting to know how to model a simple book will have to make a conceptual leap from "I have a book and want to use IIIF" to "Well, I guess my digital object that represents a book has multiple related images, so this is the cookbook recipe I will use."

I think the rest of the recipe is excellent, though. The only change I would suggest is to the title of the recipe, to make it more scannable to people looking to solve real-world challenges, and to clarify in the first sentence or two what the concrete use case is.

[scossu]

I think both @ahankinson 's and @regisrob 's approaches are valid and useful. A specific recipe may be necessary for someone looking for the specific quirks of a format, a generic one would be useful as a starting point for a use case that doesn't fit in any of the specific ones. Therefore I agree with this approach provided that more specific examples of popular formats will follow.

[scossu]

I see several issues with the link syntax not parsing (in other recipes too). Is it related to the fact that this is a preview page?

[glenrobson]

The issue with the links between recipes is the recipes don't yet exist in the master branch. Once we do the merging there will be some clean-up work to make the recipe links work.

There are also some links to recipes (mostly in the related recipes section) that have yet to be written and these will have to be linked up later. I think there is value in including these links as they prioritise which recipes get done next and also means recipes can use features from these other recipes in the Manifest without going into detail. An example in this recipe is the use of a Image API endpoint which isn't explained in this recipe but there is a link to [Simple Manifest - Image with - IIIF Image API Service] in the related recipes and that recipe is yet to be written.

[scossu]

Thanks @glenrobson . I got suspicious when I started seeing a lot of those. I'll amend my comments.

[glenrobson]

No problem, I should have put this in the description and will do for the next batch of recipes.

[triplingual]

Discussable: "is recommended: it is the human readable" ==> "is recommended: It is the human-readable", preference for initial capital letter after a colon when beginning a complete sentence; preference for hyphen where "human-readable" is an adjective (Implementation Notes)

[zimeon]

I'm +0 based for the same reasons expressed by @ahankinson above -- I think it is better to err on the side of too specific in the cookbook and then talk about generalization (whereas the specification does the opposite). However, it would be OK to get stuff out there and revise IMO

[regisrob]

Thanks all for your comments. I understand @ahankinson's point, of course I'm ok to change the recipe title as suggested (any idea would be welcome!) and adjust the Use case paragraph to reflect that (note that it also echoes @azaroth42's comment in #40 about the need for clarity in the first sentence describing the use case).

To sum up a little bit, the changes to be made (after the voting process, and depending on future comments and decisions):

• change recipe title (be more specific, it is essentially about modeling a Book)
• adjust first sentence explaining the use case (i.e. the use case is not to have "A sample Manifest for an object composed of..."
• replace "IIIF Presentation resource" by "Manifest" in the first paragraph
• get rid of the "etc." (and possibly expand them with one or two examples)
• fix english spelling per @triplingual's comment: "is recommended: it is the human readable" -> "is recommended: It is the human-readable"

[glenrobson]

Issue 41 (Recipe 9: Multiple Related Images (Book, etc.))

+1: 16 [cubap emulatingkat gigamorph glenrobson hadro irv jonhartzler joshuago78 julsraemy jwd mcwhitaker mejackreed mixterj rentonsa scossu tpendragon]
0: 4 [ahankinson azaroth42 mikeapp zimeon]
-1: 0 []

Result: 16 / 20 = 0.80

Super majority is in favor, issue is approved

[glenrobson]

Issue 41 (Recipe 9: Multiple Related Images (Book, etc.))

+1: 21 [brndgtl cjnishioka cubap emulatingkat gigamorph glenrobson hadro irv jonhartzler joshuago78 julsraemy jwd mcwhitaker mejackreed mixterj mposton-folger nfreire rentonsa scossu tpendragon triplingual]
0: 4 [ahankinson azaroth42 mikeapp zimeon]
-1: 0 []
Not TRC: 0 []
Ineligible: 0 []

Result: 21 / 25 = 0.84

Super majority is in favor, issue is approved

[regisrob]

This commit aims to address the remarks made by the TRC on July's call (summarized in the above comment): IIIF/cookbook-recipes@733b17a