Images are hard to keep up-to-date as documentation evolves, but can be worthwhile nonetheless. Here are guidelines when adding images:
All images should have meaningful alt text unless they are decorative.
Images are served as-is – pick the correct format, and losslessly compress all images.
Use absolute paths for image files so they are more portable.
Images should be responsive. This is something we should handle in the styling.
Figures are images which contain captions. Use figures to annotate what is happening in the image to the reader. Figures and their captions have some slight styling to help them stand out from surrounding text — this is especially useful for screenshots which can easily blend in to the page.
You can see that the caption helps further illuminate and provides a link to the image.