Documentation best practices: GIF images

Help / Discuss
1

Hello!

Context

In this page of documentation, we use a GIF to display a short video that illustrates the documentation (makes it more user-friendly). This is not the only page where we use a GIF.

In our documentation best practices, we explicitely say that You should save your images only as PNG.

Technically, GIF is an image format, and we use GIFs in page content with the {{image}} macro. However, it’s not always easy to replace one GIF with one or a few PNGs.

GIFs cannot be resized from content syntax without losing the animation, so I think it’d also make sense to say that they don’t have to follow the discrete sizes rule we have for other pictures (it can be way more time consuming to apply this rule on existing GIFs than PNGs).

Proposal

Update our documentation best practices:

  1. Allow the use of animated GIFs
  2. Animated GIFs can be any size.

Opinion

Here’s my +1 for both 1. and 2. .

Conclusion

Do you agree with this change proposal? Do you think we should still enforce size rules for GIFs instead?
In a week from now (12th of December), I’ll update our documentation best practices with the result of this proposal.

Thank you in advance for your feedback!
Lucas C.

2

-0

I don’t think we need animation in most cases, and it’s often abused and if we do we can always use some videos (also to be limited in usage as it’s a pain to maintain). The example at https://www.xwiki.org/xwiki/bin/view/FAQ/How%20to%20use%20a%20custom%20font%20in%20XWiki clearly doesn’t need an animated GIF which brings no value IMO and makes it harder to maintain. You could simply show 2 screenshots (or more) of different fonts used.

I’ve noticed that some developers have taken the habit of only putting animations in release notes and I find it painful as a reader. At minimum, I’d expect a fixed screenshot and if needed an animation on top, but not just an animation. For example: https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/16.6.0/Entry001/ (it’s hard to see at a glance where the source button is located and what you get when you press it)

Definitely -1 for me. There’s a reason to have the size guidelines and whether the image is animated, whether it’s a video or whatever else, the guideline remains.