| Table of Contents |
|---|
Resource links
Slide deck - improving API onboarding (API key registration)
Jolan, Nov 24 (Stakeholder interview - APIs outreach)
Brief overview of the users:
How accurate is this user persona we’re currently using?
Note that API work is often part of a person’s job (working as a developer at a CHI, or working at a startup, etc.)
The ‘task’ listed above, 'Find ways to get help from the form (https://europeana.atlassian.net/wiki/pages/resumedraft.action?draftId=2395439141 ) and customer support’ is vague - they access help (support) primarily through a Google group and the API mailbox
Note on ‘frustrations’ listed above:
About documentation: Documentation will be addressed with version three of the API, with updated documentation that’s easier to read and simpler but still detailed enough.
About not having enough examples: they do plan to have more examples in all their API docs
About scrolling - this has been addressed in the confluence (https://europeana.atlassian.net/wiki/pages/createpage.action?spaceKey=EF&title=Europeana%20API%20Documentation ) with the embeddable tables in expand boxes.
About range searches: Re-index last summer normalised the dates and solved this, and is now in their documentation.
An additional frustration Jolan has heard consistently: The documentation has become quite outdated (for over a year now) - API team is aware of this but haven’t had time to update it yet, but people do comment via the feedback semi-regularly
Note on ‘context of use’ listed above: the simplified version should be available, maybe the documentation wasn’t clear enough
The above persona is very developer-centred; what about researchers?
They differ a lot, there is a survey that shows the proportion of these users that are researchers (quite a significant portion): around 30%.
His team created the harvesting and downloads page specifically for them. They don’t want to write code themselves, just to download in csv or another file format that they’d then put into their research software. They dont really even want an API key, they just want a link to google drive where they can download data sets directly;
Creating a sub-persona for the researcher like this (data researcher, also a sub-persona of the researcher persona) may be useful;
Harvesting and downloads page would likely be really helpful in a ‘For Researchers’ page (Alba’s); and then the dev page can have a link to that
What percentage of our total users are in this group? See the user segments from 2019
Idea: Julie to check forum to get an idea of numbers; also matomo
...
Their various needs/goals (in order of priority)
“It’s something that we promised as part of an external project or tender”: Their org committed to connecting to our APIs and now they have to make it happen.
Researcher: “I want data that's in the same data model that comes from different institutions” and Europeana is the only place they can access that.
They have a startup idea and they want to use our APIs (e.g. Jama and his project Conzept)
Educators showing their class how to use linked open data without having to pay for an API key.
Other tools/services we have for them, and where they are:
APIs (currently on Pro), debug menu (currently in footer), etc
API documentation on Pro will go away and it will become the Confluence documentation;
Swagger consoles are a playground access to the API’s https://pro.europeana.eu/page/api-rest-console
Could have more prominence on the page because it’s a cool feature, where you can play with the APIs easily; Swagger console output is a much easier way to view the API and learn how our website uses it in the backend.
Either link to it from the page or embed it directly in the page. It’s more digestible bits of code that are much easier to use, and looks like this:
...
The needs of Jolan’s outreach efforts:
How does he currently promote our APIs and other developer tools/features?
They’re over marketed to ‘hey use our apis, use our data’ - so targeted physical outreach has been the most useful so far; conferences and hackathons where there’s a group of devs who are interested in the intersection of culture and development; this is more likely to get more people actually taking it up, following through, and making stuff.
The onboarding steps he follows:
gives a presentation,
prompts them to browse the website and get inspired by objects,
then he directs them to the debug page, and then they get a feel for what the data they're requesting looks like and how the requests work, get them inspired and the find something they want to use,
and he directs them to the documentation most specific for their use case
BIG LAUNCH OF HELP DOCUMENTATION IN FEB/MARCH SO IF THEY COINCIDE THAT WOULD BE NICE
How would he use a page like this, once everything is in one place at one URL?
This page would be between just surfing europeana.eu and then going into the deep documentation and active usage of our data; to help support this onboarding (above).
...
Page content - is it complete? What is missing?
Page hierarchy - most to least priority?
Page visuals - potentially will get some customs icons and illustrations.
What are some initial keywords/visual associations for APIs?
API = sockets and plugs, electrical wiring, usb stick, fitting together, machinery, cogs, separate parts working in unison together, funnel/filter, little goblins/creatures going and gathering your data and moving it around, working behind the scenes
API key = key? access cards, access
For the other page concepts?
CMS - filing cabinet
Localisation - Multilingualism, speech bubbles, globe and flags
Performance - speedometer going fast, speedy/fast
Protection - shield? Likes the heart
Richard, Lutz & Leonie, Feb 2024 (User feedback - as users of the Europeana API’s)
First section:
Show what's available in an easy to understand way, especially if the course isnt ready
Show only Record, Search, IIIF
Guided approach: How to use them together - Search, Record, IIIF as a core use case that makes sense chronologically
May add more eventually, but this is a strong start. Include "additional apis are available" somewhere lower in the page, just for completeness
"Most likely you'll want to use the Search api, this will help you find items...."
linking to documentation: Linking to these pages is a big jump, and an enormous amount of information to dump them onto
...
Also on acknowledgements page - higher level, start with APIs, then JSON stuff, then these three things
Hugo, Feb 27 (Stakeholder feedback - as PO of APIs)
Onboarding improvements
Codepen section: This section will contain training resources; when the trainings are available, they should go here instead of this. If we implement this, it should be improved a bit (see Lutz's comments) and approved by Hugo.
...