Image best practices

First, a quick note about working with images. A lot of guidance around file types will discuss two key factors:

• File overall size: If you have a single image on a page, this probably won't matter too much, but if you have twenty, it might matter a great deal.
• Whether a file type has lossless or lossy compression: this has to do with how detailed the image is/how much it compresses the original file. In general, lossless types are more detailed, but they are also often larger in size.

There are a wide variety of file types for images and pros and cons to using each. (And if you search for answers on this, you'll also find a wide variety of advice!) We're summarizing the things we've found most useful.

The dominant file types for images include:

• .jpeg or .jpg (JPEG)
• .png (PNG)
• .webp (WEBP)

Selecting between these largely comes down to a tradeoff between file size and file compression or loss.

The best choice for you is definitely an "it depends" situation. Let's look at each format in more detail:

• JPEG is the default original in online image quality and is still considered a good default for actual photos shared online. Photos in particular can be very bulky in file size, and the JPEG format goes through a "lossy" compression--meaning that as it compresses, it strips out a lot of detail, and therefore lowers the file size.
• PNG is usually larger in size than JPEG, but they are more specialized for detailed, high-contrast web graphics because they have a lossless compression--so if you do resize, your display won't look blurrier as a result. They also support transparent backgrounds, a useful feature if you're sharing icons or other oddly-shaped images. (PNG has been our own default for screenshots for years.)
• WEBP is a "newer" standard, owned and pushed by Google. On the surface, it combines the best of both worlds: it has both lossless and lossy compression much closer to PNG in behavior, but the sizes are much smaller, comparable to a JPEG. Like PNG, it supports a transparent background. And unlike both JPEG and PNG, it supports animation (which you otherwise would need a GIF or an SVG for). If you're running pages with many images on them, WEBP usually creates faster load times and better performance, which can help with SEO. (We are slowly moving to this standard.)

Some additional resources if you'd like to explore this more:

• Adobe has a fairly good write-up comparing JPEG vs. PNG
• Mozilla's Image file type and format guide

Icon files are most often available in one of two formats:

• .png (PNG)
• .svg (SVG)

Honestly, either one of these options generally works well for category icons or article thumbnails. They're both fairly lossless, they both work on transparent backgrounds, and they're designed to scale up and down.

Here's a quick side-by-side comparison, though Adobe has a more detailed PNG vs. SVG write-up if you want a deeper dive:

Really, either will work, but we lean toward .svg for these reasons:

• SVG is slightly smaller and faster to load, so it gives you better page load times. Especially if you're displaying a lot of icons on a page, this matters.
• SVG files will scale down/up more gracefully than PNG, so it shouldn't matter as much what the original dimensions it was generated for were.
• Since icons are often present on every page, the accessibility/text-based scanning makes your general navigation and presentation that much more accessible.

But the big caveat with using SVGs is that they do NOT play well with PDFs. So above all, consider where/how the icon is used. If it will somehow end up in a PDF, don't use an SVG.

Our editor gives you several ways to resize images. While they do all work, here are some of the tips we have for working quickly with them:

• When you insert a new image, it gets added with "auto" height and width. This allows for good responsiveness on different device sizes.
• The fastest way to resize is to select an image and then drag one of the corners to resize it.
  • This will automatically set a percentage value in the width, which will keep things responsive. You also don't have to fuss with percentages. But your resizing can be somewhat biased by your screen size!
• You can also select an image and then select the Change Size control to add your own size adjustment. This control opens a small pop-up where you can specify a Width and Height for the image.
  
  The Change Size control in the image menu
  If you use this control:
  • Use percentages (like 50%) instead of pixels (like 200px). Percentages keep the image more responsive on different screen sizes, which is why we use them in the corner drag control.
  • Adjust the width only; keep the height set to auto.
  • Don't ever set width to be blank/nothing. This will prevent your image from appearing in PDFs.

If your knowledge base needs to be WCAG-compliant, or if you just want to incorporate good accessibility practices into your documentation, images can be a tricky content element.

The easiest best practice we can offer is that alternative text (alt text) is your friend! This text provides a short description to help those with screen readers or other assistive devices so they aren't losing information conveyed by the image.

Official accessibility guidance classifies images as one of seven types. Alternative text entry varies based on the image type.

Here's a quick breakdown of the different image types:

For adding alternative text--including how to add the empty/null alt text--refer to Add alternative text to images.

W3C's Web Accessibility Initiative is the ultimate resource on these details; check out their Images Tutorial for far more detailed guidance than we could ever provide; their Tips and Tricks can give you some good guidance on writing alternative text, too.

Gifs and animations are sometimes a contentious visual asset in knowledge bases (not least of all because there are competing factions on how to pronounce gif--are you a jif or gif supporter?).

Four factors should impact your use of gifs:

1. Accessibility
2. Maintainability
3. Performance
4. Usefulness of conveyed information

Accessibility

Gifs, like other images and visual content, may be used to convey information or for decorative purposes. Evaluate them just as you would other images and use appropriate alternative text. Refer to Accessible images for best practices on visual accessibility and Add alternative text to images for working with alt text.

The one way gifs depart from static images is that looping gifs can be classified as flashing content. In accessibility requirements, you want to avoid flashing content that may present a risk for seizures, physical reactions, and other photoreactive responses.

Broadly speaking, this means you:

• Do not include content that flashes at particular rates and pattern
• Warn users before flashing content is presented, and provide alternative
• Provide mechanisms to switch off animations, unless they are essential (source)

We like the guidance provided by Accessible Web:

Animated gifs can be accessible if they are set to stop after 5 seconds or if users are presented with a way to pause it, if they have alt text and if they do not contain blinking/flashing.

You should also ask yourself if there is another way that the message can be communicated. Would a still image do? If not, think about providing an alternative or some way that users can forgo the animation or switch to an embedded video.

A useful tool when checking your gifs for flashing may be this Photosensitive Epilepsy Analysis Tool. You want to make sure the animation won't trigger seizures in people who are sensitive to flashing.

If you're using looping gifs, consider something like Only play GIFs while hovering.

Maintainability

Animated gifs can be harder to maintain than static images, especially if the gif is of a user interface that changes frequently. Instead of grabbing a single screenshot, someone must re-create the original action(s) shown in the gif. The longer the gif, the more involved this process becomes.

Performance

One gif on a page--provided it's short--likely won't hurt your page load times or performance. But if you use a gif after every numbered step on a 20-step process, it definitely will.

Usefulness

Last but not least, is a gif the best way to present this information? Would a static image, or a couple static images, convey the same information? Gifs don't have the start/stop control that videos do, so if it's a complex or lengthy process, someone may be stuck watching the gif repeatedly to try to get the information. Make sure that a gif truly is the best way to present the information.

Recommendations