Handle videos in the help page

Development
#1

Hello!

Lately we’ve received the report of an accessibility audit of XWiki made by Dataport. I reported all the points they noted and one of those is XWIKI-21375: Videos on the help page don’t have alternatives. The page mentionned is similar to this one from dev.xwiki.org.

We decided for 15.5 that we’d remove the Youtube embed from the homepage for XWIKI-21028: Remove the video on the XS home page (forum topic).
However in this case, the videos hold an important role in the content of the page and it’s not possible to remove it without any other change.

In order to solve the aforementionned issue, I propose to

(1) Add a collapsible transcript section for each video.

I think there’s a couple other solutions that could do, here’s them and why I thought they were worse than (1) :

(2) Remove the help/video page
I think we should avoid this as this would worsen the experience for a new user. Those videos contain a lot of info, and unless we make sure all this info is in another place in the help section, this page cannot be completely deleted.

(3) Embed videos as attachments and add transcripts to them.

This was used in the help/application page, but for shorter and lower quality videos. I don’t think including video files in the build is a good practice and it might create problems down the line.

What do you think of this idea?
I know there were some issues with youtube embeds about user privacy, but I’m not sure this is quite as critical on this page.

Thanks,
Lucas.

#2

+1 for „collapsible transcript section for each video“

Thanks

#3

That’s easy to write but it seems hard to implement.

@CharpentierLucas What’s the proposal for implementing this (and to maintain it)? I think your proposal needs to include this. It seems quite hard to do for me, especially since XWiki supports lots of languages. I guess your proposal would be to provide this as translation keys on l10n.xwiki.org and let the community provide the transcripts in all languages. I have no idea, if community members will be ready to do this hard work.

Also note that we already have a hard time having up to date videos. So much that I don’t think that any video is up to date nowadays… So now, this means multiplying the effort by another factor. The maintenance of the transcript is really a lot (everytime the video is updated it needs to be redone).

I’m not sure I understand option 3:

How is that different from option 1?

#4

I think that’s the way it is. It’s hard work for the first time but is getting easier for video updates. And I think it’s better to have this option. These transcripts will help for a better match while searching for specific help btw.

#5

Are you proposing to help out to write these transcripts? :slight_smile: Thx

#6

My opinion is that we shouldn’t do it if it takes more time from the core committers (they have already a lot of work, including constant fixing of bug fixes, and they’re already stretched out). The way to make it work is if this could be done fully by the community, and maintained (if the transcript doesn’t match, then it becomes a bug).

#7

and as I said, we’re talking about providing transcripts when we cannot even maintain the videos themselves… :wink: We need a solution for this too.

#8

Another idea is that these videos are NOT necessary to learn how to use XWiki. They’re just (currently outdated) visual bonuses. For each video, we could link to the documentation pages on xwiki.org explaining how to use the feature that is in the video. This would avoid having to provide a transcript while still providing a solution for accessibility.

1 Like
#9

We “removed” all those videos from our users sight in the “Help” space. The look of the wiki in the videos isn’t what I see today. So yes, they have to be updated if used.

I personally don’t like watching videos instead of reading a “manual” because I can’t scan and go forward in my own speed. (That’s why I prefer “Documentation” space over “Help”) So I wouldn’t offer help for updating those videos. If they will be updated I will help to transcript them. (And to translate them to german.)

But in the end, I think the videos are rather dispensable.
Simpel

#10

The videos are not really maintained and don’t cover multiple langages, so I figured writing a ‘one time english transcript’ would be good enough of a solution. Note that the video has no audio, I think the transcript will probably be 10 lines only, 20 if we add details that are not written down in the video.

Then Option n°2 is probably the best :slight_smile:

It was a similar idea, but also involved replacing the youtube embeds with video attachments.

Updated proposal:

2. Remove the Help/Videos page and add three new help cards to replace it

For each video, we search a text equivalent in the doc:

new help card means adding a card on the ‘Help’ Webhome:
HelpWebhome
If this proposal is accepted, I think I’ll update the help card categories so that they go along with the changes.

What do you think of this updated proposal?

Thank you for the feedback :slight_smile:
Lucas

#11

That cannot work for accessibility since it would mean XWiki is only accessible in some language and not others, since these other languages are also supported…

I’m not sure, see below.

What’s the advantage from a WCAG point of view?

We introduced videos because lots of people like watching videos and prefer that over text (it provides more context and shows the UI). If you’re not fluent in English for example, it can help to watch the video (as all the docs on xwiki.org are in English).

My take is that we should try to keep the video (but do a sprint on updating them so that they’re up to date; we can ask for help to the good folks of XWiki SAS, maybe they can spare some time from their marketing team ;)) and below each video add several links that explain the concepts listed in the video. In this manner we keep the videos but also solve the accessibility issue by pointing to precise docs for the tasks demonstrated in the video, thus reducing the maintenance effort.

Question to the WCAG experts: is this acceptable to pass WCAG 2.1 AA?

Note: we should also update User Guide (XWiki.org) with the links we find for each video.

Now, I’m not entirely against dropping videos from the help page but 2 things:

  1. I think we should check with XWiki SAS marketing team to see if they’re willing to help first
  2. If we drop them from the Help app then we also need to drop them from the xwiki.org documentation at User Guide (XWiki.org)

WDYT?

Thanks

#12

This variation was not related to accessibility but to data privacy other reasons why we would like to remove Youtube embeds from a default distribution. I don’t understand these stakes too well, but they were mentionned when we discussed the video on the home page.

The accessibility report from which this discussion originates mentionned Success Criterion 1.2.3 Audio Description or Media Alternative (Prerecorded) which is an A level criterion:

An alternative for time-based media or audio description of the prerecorded video content is provided for synchronized media, except when the media is a media alternative for text and is clearly labeled as such.

We could consider this is a media alternative for text, but we would need to label it as such (which is more or less what you proposed by “pointing to precise docs”). The report also mentionned Success Criterion 1.2.5 Audio Description (Prerecorded), which can also be disregarded in the same situation (clearly labelled alternative to text) because of the definition of synchronized media:

audio or video synchronized with another format for presenting information and/or with time-based interactive components, unless the media is a media alternative for text that is clearly labeled as such.

With WCAG 2.1 AA in mind, I think we can pass if the text alternative is clearly labelled and similar enough so that we can legitimately call it an alternative :+1:

So from what I understand the solution you propose could be summed up as

4. Label each video as an alternative to some text documentation.

After looking at this, n°1. or n°3. by themselves wouldn’t be enough since I don’t see us maintaining a transcript AND an audio description in multiple languages.

I don’t like n°2. too much since we don’t want accessibility changes to worsen the experience for the average user.

Thanks,
Lucas.

#13

Started a proposal for a fix in this PR.