feat: add alt text criteria to style guide

[mjang]

Proposed changes

Add criteria for alt text to the style guide at https://github.com/nginx/documentation/blob/main/templates/style-guide.md

Checklist

Before merging a pull request, run through this checklist and mark each as complete.

• I have read the contributing guidelines
• I have signed the F5 Contributor License Agreement (CLA)
• I have ensured that documentation content adheres to the style guide
• If the change involves potentially sensitive changes, I have assessed the possible impact
• If applicable, I have added tests that prove my fix is effective or that my feature works
• If applicable, I have checked that any relevant tests pass after adding my changes
• I have updated any relevant documentation (README.md and CHANGELOG.md)
• I have rebased my branch onto main
• I will ensure my PR is targeting the main branch and pulling from my branch from my own fork

Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation.

Please refer to our style guide for guidance about placeholder content.

[github-actions]

✅ Deploy Preview will be available once build job completes!

Name	Link
😎 Deploy Preview	https://frontdoor-test-docs.nginx.com/previews/docs/119/

---

[ADubhlaoich]

The guidelines read incredibly excessively, and like a negatively-framed shopping list of specific mistakes someone has made in the past instead of positively-framed advice on how to do things well.

There are three sentences dedicated just to punctuation. Line 418 already includes a lot of the critical information needed to write alt text, too.

We could just just be linking to the WAI Tips & Tricks instead.

[mjang]

The guidelines read incredibly excessively, and like a negatively-framed shopping list of specific mistakes someone has made in the past instead of positively-framed advice on how to do things well.

There are three sentences dedicated just to punctuation. Line 418 already includes a lot of the critical information needed to write alt text, too.

We could just just be linking to the WAI Tips & Tricks instead.

Thoughts:

• It's the kind of list that (should be) translatable to Vale (The WAI Tips and Tricks IMO are too general)
• It's taken from the GitLab style guide: https://docs.gitlab.com/ee/development/documentation/styleguide/#alternative-text
• IMO line 418 is too long

[ADubhlaoich]

Thoughts:

• It's the kind of list that (should be) translatable to Vale (The WAI Tips and Tricks IMO are too general)

• It's taken from the GitLab style guide: https://docs.gitlab.com/ee/development/documentation/styleguide/#alternative-text

• IMO line 418 is too long

Should is a very loaded word because we haven't instituted Vale as a requirement for documentation pull requests. If it's intended to be, then the effort of this PR is premature optimization. I don't have any reason to treat GitLab as an authority just because they already did it. I would have raised the same objections there, too.

While the WAI Tips & Tricks are probably a bit too general, it is also part of the W3C, which is the actual authority that defines how browsers should behave. This also means that they define how the web should be accessible, and I am thus more inclined to treat them as a primary source of advice or information.

If 418 is too long, it should be reworked or removed: I don't feel that a list of items should have preferential "weight" over a paragraph just because the formatting is different.

[mjang]

More recent style guides for UIs are moving towards "Do/Don't" lists. And by definition, they include "negative" inputs. What I'm proposing, based on GitLab guidance, is no different.

IMO, the discussion of "should" and the reformatting of line 418 is besides the point (and a distraction).

Writers need these types of lists so they know what to do, and what not to do.

• They won't get this kind of guidance from the WAI tips and tricks.