Secret ingredients to quality software


Figures - Do you add useful and concise figure text?

Last updated by Tiago Araújo [SSW] on 28 Apr 2021 04:21 pm (6 days ago) See History

When you add an image to a website or application, it is so useful to add a figure underneath it to describe your image.

It's the best way of ensuring you catch users' attention to the content of your page. When you're scanning a newspaper for interesting articles, you'll check out the pictures, read the accompanying description, and if it sounds interesting you'll go back and read the article.

Users read websites in a similar fashion. Catch their attention with an image, and then keep it with a useful description. Don't just describe what the image is; say what it's used for in the context of the document.

Tip: Prefix it with the actual word "Figure: ".

good caption
Figure: Good Example - Some nice useful text describing the image

It is especially important that images and captions serve a purpose, as opposed to graphics which are there solely for design.

Tip #1 - Give bad and good examples

When possible, use "bad" and "good" examples to clearly explain Dos and don'ts. At SSW we always show the bad example first, then the good example. You will see samples of this in the next tips below.

Tip #2 - Bold your captions


Figure: Caption not bolded


Figure: Caption is bolded

Tip #3 - Describe the actions in your captions

Especially for screenshots, it is a good idea to have your figure describe the action the user would take:

Figure: This is the screen

Figure: Bad example - Vague caption description

Figure: On the screen, choose the execution method

Figure: Good example - Clear caption description

Adam CoganAdam Cogan
Tiago AraujoTiago Araujo

We open source. This page is on GitHub