IIIF Manifest Editor —commentary on first round of user group feedback
Digirati are working on a new IIIF Manifest Editor as part of Practical Applications of IIIF, a Foundation project within the the AHRC-funded Towards a National Collection Programme. We asked for comments from stakeholders and potential users on the product vision statement, and a first batch of user narratives. This blog post responds to the questions and comments raised by the product vision — further posts will dive deeper into the narratives.
Feedback on the Product Vision
This was felt to be clear, and the value of the overall objectives to the cultural heritage community was high. We acknowledge the challenges in making a tool that can work for users with widely differing levels of IIIF knowledge: this is one of the hardest tasks.
The ambitiousness of the project as a whole was also a theme. We agree: there is potentially a long roadmap beyond the first production release; we want to favour usability over feature lists at the outset.
Concerns about sustainability were raised. These and some other minor clarifications have been added to this revised product vision statement. Sustainability is also discussed in the final section below.
Clarifying what the Manifest Editor is
Several comments were made about licensing and costs. The Manifest Editor is an open source, client side JavaScript application released under the MIT licence, which effectively means anyone can take it and do what they want with it. It does not require any server-side components. People can take the source code and host it at low cost, or no cost (e.g., in GitHub Pages). We hope institutions will find it easy to integrate it into their existing workflows and tools and we’ll provide examples of how to do this.
That doesn’t help the casual or independent user. They aren’t going to set up or configure anything.
So there will also be a hosted version of the Manifest Editor, that anyone can just walk up to and start using. This is just like the hosted instance of the Bodleian Manifest Editor. It’s a JavaScript web application, there’s no login, no account required, no collection of user data. Users will be able to visit it on the web and assemble a Manifest.
The naming of things
A stated goal of the Manifest Editor is to be usable by people unfamiliar with IIIF. But it’s called a “Manifest Editor” — what’s a Manifest?! Do we fail before we’ve even got started? “Terminology is a barrier to entry” was mentioned in initial feedback: what can we do about this?
This is a subtle problem. Should we call it a Manifest Editor? Does its user interface label things “Canvas”, “Range”, “Annotation” and so on? Does the tool use IIIF vocabulary when it’s being used in a IIIF training session but a different vocabulary when it’s being used by someone who is thinking of it more like PowerPoint? For example, should it use “Slide” instead of “Canvas” if the user has been given the editorial, content-production task of assembling a slideshow? Or should it be consistent, and not change the names of things for different contexts?
Firstly, the application name itself. It could more precisely be called IIIF Presentation API Editor, as there is no reason why it won’t edit IIIF Collections in future, or be used for creating Annotations without actually modifying a loaded Manifest. IIIF Presentation API Editor is not a good name: the word “presentation” makes it sound more like PowerPoint. Going the other way — should we avoid mentioning IIIF? Call it a Digital Object Editor or something equally free of specific IIIF terminology? That is also problematic, as it’s too general — what kinds of digital objects? Define “digital object”… Can I edit any digital object here? No — only IIIF digital objects… ah, why didn’t you say so?
We think the application should be called the IIIF Manifest Editor. It should include the term IIIF, and it should include the term Manifest, even if its users aren’t sure what that is. There are already other Manifest Editors; the term Manifest is not a random word, it has connotations from other domains. Not including IIIF in its name will require continuous clarification of what it can be used for, and including Manifest in its name nails it down closely enough to its purpose without being pedantic.
Secondly, the use of IIIF terms in the user interface. Using terminology from a domain to describe the things in that domain does not mean that we expect or require users to know what those terms mean — they are labels for things within the user interface. Something can have a name and be usable before we understand why it has that name. We navigate much of the world with a partial or provisional understanding of complex models, and for many models that understanding is all we need to use it productively.
We would hope to build a user interface that conveys visually how the IIIF domain model works. The user’s own exploration and experimentation, and the information architecture of the user interface, should allow the user to develop an informal understanding of the parts of a IIIF Manifest, and what is possible. The user interface can teach IIIF through good design; the user comes away with a conceptual understanding of how it works by seeing how the interface presents it to them, aided by metaphors and patterns the user recognises from other software.
That conceptual understanding of the model could emerge from alternative labels for the parts of the model (like Slide instead of Canvas), but the particular label is less important than its visual presentation and affordances for understanding what it does. Concepts in IIIF (Manifest, Canvas, Range, Annotation, Collection) and their properties (label, seeAlso, homepage, structures, items) are not random words, but terms that emerged from their own design process; that process was very aware of the potential to mislead and confuse through poor naming. This sounds contradictory — “the labels don’t really matter”, but “the labels we already have are the best”. It’s not meant to be contradictory; rather, that the user interface design is what should give the different parts their meaning; as we must call them something, we should use the terms from the model, as they are probably the best, and even if they are not, they are the terms that the user will encounter everywhere else.
We should use these terms, but provide ample links to definitions (e.g., with tool-tips, glossaries, contextual help). Here are some IIIF term definitions and here are some more, on the IIIF site.
A good way of thinking about the problem was suggested by the feedback — the way you edit HTML in WordPress: “the basic user can make a website without even seeing any HTML or, realistically, knowing what HTML is.” This is true of the Manifest Editor too, for IIIF Manifests the terminology analogy is instructive: what are the equivalent terms? While WordPress users don’t ever need to see the raw HTML much less make sense of it, they do know that they are editing a thing called a web page, and they have probably heard of the term HTML.
We assume that people know about web pages or slide decks, so we can use these labels for the things people are creating. The Manifest Editor needs to convey “I am a tool for making X” and the best label for “X” probably involves the terms “IIIF” and “Manifest” — one aim of the tool is to encourage IIIF knowledge and adoption, after all. It’s not that we don’t appreciate that familiarity with IIIF is orders of magnitude less common than familiarity with web pages, but that we aren’t helping users by using other labels; sooner or later we need to call it what it is.
The Manifest Editor will allow you to construct a IIIF Manifest without ever looking at the raw JSON, just as a visual HTML Editor allows you to make a web page without ever looking at the raw HTML. The IIIF Manifest Editor is a visual content creation environment that can be put to all sorts of uses, because IIIF Manifests can be put to all sorts of uses, but defining Manifest as the thing that you’re making in the tool is, we suggest, a necessary step.
Imperfect analogies
While PowerPoint and similar tools are great analogies to use when explaining IIIF — “a Canvas is like a Slide” — those analogies are not perfect, and trying to bend IIIF too far to fit eventually ceases to be a useful metaphor for UI and learning, and starts to make some tasks harder. There is more apparent structure in a Manifest than in a slide deck. A Manifest is also a document that usually has links to many other documents on the web, for both information (“here is this item’s homepage, here is my publisher’s homepage, here is a some descriptive metadata”) and content (“here is the image of this painting, and here is a IIIF Image Service attached to it”). It has multiple formal mechanisms for linking, unlike a slide deck.
A IIIF Manifest is a Linked Data document that describes the information needed to present a compound digital object on a web page. As many presentations of digital objects are made up sequences of large interesting images, the slideshow analogy is immediately useful. But a Manifest is not a slide deck. So while we will borrow heavily from slide metaphors where they help understanding and intuition about what the UI does, we will not try to bend them too far.
How important is the visual Canvas?
If we’re using PowerPoint/Slides/Keynote metaphors, it sounds crazy to suggest that the central visual editable canvas is not important. However, for some Manifest Editor use cases it is less important that what happens around it — the ease of navigating to different parts of the manifest and editing the properties, resources and links in those different parts. Most manifests are sequences of images: they don’t have complex scene composition requirements but they do need good metadata-editing UI. Thumbnails and rapid, easy preview are perfectly sufficient to create many Manifests.
This suggests that we can make a good user experience based on navigation and field editing UI — one that also works well on smaller screens.
This doesn’t mean that a large Canvas to work on isn’t important — it’s essential for complex scene composition. It’s just that it’s not always that important — which is generally not true for PowerPoint.
The problem of Persistence
Many online tools like this suffer from an immediate usability problem. No matter how intuitive and pleasurable it is to assemble a digital object, what happens next? Users need to:
- See what their work looks like as they go, in common IIIF viewers like UV and Mirador, and sometimes in custom IIIF-consuming user interfaces
- Save their work somewhere for the long term, so they can come back to it tomorrow or next year, and share it with other people — that is, publish it to the web
The design of the Manifest Editor will make “Save” UI and functionality pluggable — if you are running your own Manifest editor you could configure a plugin which allows loading and saving to your own repository, including hooks to ensure compliant identifier generation. We can also develop a GitHub integration so users can push changes straight to GitHub from the Manifest Editor.
This still doesn’t address the immediate functionality problem for casual, walk-up users. They need those two bullet points too. So we have developed a service that allows both of the above scenarios — a hosted service, independent of the Manifest Editor, implemented as a pluggable feature. Any user of the Manifest Editor can preview their work as they go, and any user of the Manifest Editor (in any instance of the Manifest Editor) can save their work to a permalink — like a Google doc — that they can share and will be available for the long term.
But… we said “it does not require any server-side components”. This is still true — it does not require this service — you can build manifests and download them (the JSON file) without saving to a permalink. The service just bypasses the immediate problem of getting your work onto the web. We want to make this as frictionless as possible, so there is no cost and no account required for users — it’s just there, anyone can save a Manifest to the service as a permalink. We believe the cost of running this will be so low that it’s cheaper to demonstrate a solution to the persistence problem this way now, and then concentrate on UI and editing functionality, than to do anything more elaborate, or more locked-down, with user accounts and billing and all that rigmarole.
It does mean, though, that users rely on us to maintain that permalink, if they choose to save to this service.
The other problem of persistence
Anyone can use the Manifest Editor to assemble new Manifests that include parts of existing hosted IIIF Manifests, or existing hosted image services, or in fact any asset (image, AV) already hosted somewhere on the web. And like the Bodleian editor, this functionality is completely sufficient for many use cases — such as working in an environment where the images are already on the web, or even are already IIIF, or where users have other external ways of publishing those images before referencing them from a Manifest.
But many users will come to the tool with the expectation that they can turn some images on their computer into a Manifest that they can then publish and share. It’s no good publishing a Manifest if it references images that only exist on your computer. It’s not like a PowerPoint deck that bundles all the images into a single distributable file. It’s more like a web page, with image tags. If you publish an HTML page on the web, it’s no good unless you also publish all the images it points to.
This, at the very least, means that adding an image from the desktop publishes that image on the web at a URL. It means that the Manifest Editor pushes images from the desktop to some form of image hosting, if you want to use it to publish both IIIF and the assets the IIIF points to. And ideally, adding a high resolution TIFF to a Manifest from your desktop not only publishes it to the web, but does so as a IIIF Image service, so you get all the benefits of deep zoom, bandwidth optimisation and multiple formats.
This is a very different problem from the hosting of the IIIF Manifest itself, via the permalink. We do have solutions to this problem, but we don’t want to make the Manifest Editor dependent on our particular solution. Again, a plugin model will support integration with services for hosting of the media content — which might be a commercial offering (like our DLCS platform) or might be institutional IIIF infrastructure (image servers and associated storage) or might be simpler static hosting mechanisms, e.g., using GitHub pages.
While we will include integration of the IIIF Manifest Permalink service as a demonstration of plugins for saving the Manifest itself, we won’t, in this phase, be providing integration for hosting images and turning images into IIIF image services. The Manifest Editor is very usable without this, in a way that it isn’t without persistence of the Manifest itself. But just like the Save mechanism, import of content is pluggable — this is the hook for integrating with a hosting provider or your own repository.
We’ll come back and develop those plugins later. And others can develop their own plugins here, too.
The uses of Digital Objects
In our earlier version of the Manifest Editor we put too much emphasis on the tool being a self-contained content creation environment. You could use it to create different kinds of digital exhibits for the V&A, you could use it to create exhibitions for Delft (see this article), as well as general purpose manifests intended for regular viewers. The user experience differed depending on these modes, in particular the ability to preview the different custom outputs right there in the tool.
The new version will be much more consistently a Manifest Editor. All previewing is external to the tool, in whatever environment you want to pass a Manifest URL into. If you develop a custom user experience that’s driven by a Manifest, you don’t need to also create a plugin for the Manifest Editor to preview it — you just add your preview environment URL to the configuration.
Sustainability
We are well aware that just because there are no required server dependencies — no hosting bills that need to be paid every year — that doesn’t mean the codebase takes care of itself. Some, but by no means all, of the foundation components of the Manifest Editor are part of iiif-commons, and are used by other projects beyond this one.
We are also well aware that while the licence can be as permissive as you like, allowing anyone in principle to support and develop the editor further, in practice a community of knowledge and support is required to sustain a tool like this.
Digirati will take things as far as they can by providing ongoing governance for new releases; as well as support, development and IIIF hosting services for those who require it. But if cultural heritage organisations want this tool for the long term it will be important for the community to rally behind it, through adoption, engagement with the product roadmap and ongoing funding. We are optimistic that this tool is valuable enough to provide the necessary incentives for this to happen.
Further reading
Technical approach is outlined in the Wiki:
https://github.com/digirati-co-uk/iiif-manifest-editor/wiki
Ideas that feed the Wiki come from discussions:
https://github.com/digirati-co-uk/iiif-manifest-editor/discussions
The project board, if you are interested in work-in-progress:
https://github.com/digirati-co-uk/iiif-manifest-editor/projects/2
