[WIP] Add information about alt text

[heitortsergent]

Add guidance about alt text and figure captions.

[jdbaldry]

I love this already!

I think it will be a great complement to https://github.com/grafana/website/pull/15843.

[imatwawana]

This is great, thank you! I left one question/comment about the figure shortcode but other than a couple wording things, I think this is good.

[imatwawana]

I'm thinking we should add an example using a figure shortcode here as well.

Speaking of the shortcode, the alt parameter is indicated as not required and I'm sure it isn't for the shortcode to work; should we change that or add a note there to clarify what's meant by required in that context? cc @jdbaldry

[jdbaldry]

I would like to make it required but it will break the website build if I do since so many invocations do not have that value set.

In my PR, I first emit a log warning which we can use to identify all the misuse. Once that's cleaned up, we can make it required.

[heitortsergent]

I updated the PR to include an example with the figure shortcode as well. :)

[github-actions]

Overall readability score: 60.16 (🟢 +0.09)

File	Readability
index.md	64.51 (🟢 +4.01)

View detailed metrics

🟢 - Shows an increase in readability
🔴 - Shows a decrease in readability

File	Readability	FRE	GF	ARI	CLI	DCRS
index.md	64.51	50.73	9.32	9.8	11.7	7.42
	🟢 +4.01	🟢 +8.56	🟢 +0.28	🟢 +0.4	🟢 +0.47	🟢 +0.27

Averages:

	Readability	FRE	GF	ARI	CLI	DCRS
Average	60.16	47.07	9.64	11.77	12.13	7.33
	🟢 +0.09	🟢 +0.2	🟢 +0.01	🟢 +0.01	🟢 +0.01	🟢 +0.01

View metric targets

Metric	Range	Ideal score
Flesch Reading Ease	100 (very easy read) to 0 (extremely difficult read)	60
Gunning Fog	6 (very easy read) to 17 (extremely difficult read)	8 or less
Auto. Read. Index	6 (very easy read) to 14 (extremely difficult read)	8 or less
Coleman Liau Index	6 (very easy read) to 17 (extremely difficult read)	8 or less
Dale-Chall Readability	4.9 (very easy read) to 9.9 (extremely difficult read)	6.9 or less

[imatwawana]

LGTM!

[heitortsergent]

Thanks for the review @imatwawana @jdbaldry! 🙇