Alt Text in links and images
Alt text is the descriptive text for links to URLs or media. Learn how to do it right.
Alt text is an essential accessibility tool (opens new window) for users with visual impariments. It's a piece of text that explains the subject of an hyperlink or image so that screen readers can read it to users.
It ensures that those readers get the same benefit from photos, charts, and other visuals that fully sighted readers get.
# Usability tips
- Include alt text for links and images
- Add an empty alt text (opens new window) for decorative images
- Describe the content of the image instead of using the generic term "image". For example, "Screenshot of" or "Diagram of"
- Keep alt text to a maximum of 10-15 words
- If an image is so complicated that requires more than a short description to provide value to readers, consider providing a link to an explanatory text
- Do not editorialize alt text. It should not include assumptions or interpretations of the image or describe subjects’ intentions
- Make sure the description of the page's content is accurate to avoid pogo sticking (opens new window)
- Avoid using "link" as most screen readers already add that word
- Avoid duplicate links (opens new window) in the same article unless the links are very apart from each other.
- Unless it's a glossary file
- Unless it's email addresses (Although an article with duplicate email addresses could be rewritten!)
# Style tips
- Avoid Saxon Genitive "'s" - For example "Acmecorp's website"
- Use consistent terminology when referring to content. For example, don't mix "Article about $" with "Chapter about $"
- Follow the capitalization of proper names. For example, write "iOS" not "iOs", "venv" not "VENV"
- Use official names. If the website is called, "Acme Help" don't call it "Acme Support Center"
- Use sentence case throughout the text unless the first word is a proper noun that is lower caps
- Don't write "Home Page", just write "website". For example, "Acme website"
- Introduce anchors with the hashtag symbol (#)
- Spell anchors in lower caps
- Replace spaces in anchors with an hyphen (-)
# Examples
You can copy and paste these examples and just replace dummy names. This will ensure consistency.
# Links to your product's main website
| When referring to | Write |
|---|---|
| Acmecorp home page | Acmeproduct website |
| Acmecorp product or feature overview | Acmeproduct Superfeature |
| Acmecorp list of features | List of available Superfeatures |
| Acmecorp signup page | Acmeproduct trial account signup page |
# Links to other sub-sites of your company
| When referring to | Write |
|---|---|
| Acmepr subsite home page | Acmecorp Help Center |
| Specific Acmecorp subsite concept documentation | Acmecorp Help Center documentation about Superfeature |
| Specific Acmecorp subsite how-to documentation | Acmecorp Help Center documentation on how to Manage Superfeature |
# Links to your documentation-subsite
For example, developers.acmecorp.com.
| When linking to | Write |
|---|---|
| Acmecorp subsite definition list | Acmecorp Developer Hub glossary |
| Acmecorp subsite definition | Glossary definition of supercalifragilisticexpialidocious |
| sample file on Acmecorp's GitHub mentioning filename | Sample file samplefile.py on GitHub |
samplefile on GitHub | Sample file on GitHub |
| Generic info about Acmeproduct, such as about.md | Overview article about Acmeproduct |
| Acmeproduct OpenAPI spec or subsite | Acmeproduct API exporer |
| Acmefeature code snippet or example | Sample code for Acmefeature |
| How-to article to achieve X in Acmeproduct | Article on how to create Acmeobject |
| Concept article about Superfeature | Article about Acmefeature |
| effortless file in Acmecorp's GitHub repo | Requirements file on GitHub |
# Links to 3rd-party websites
| When referring to | Write |
|---|---|
| Software download page in requirements | Software (version) download page |
| Software documentation page in requirement | Software (version) documentation page |
| Listing requirements to make 3rd-party Software work | List of requirements for Software |
| website home page | Acmecorp2 website |
| website documentation home page | Acmecorp2 documentation |
| website concept documentation | Acmecorp2 documentation about Superfeature |
| website how-to documentation | Acemecorp2 documentation on how to create Superobject |
| Wikipedia or Dictionary entry | Definition of Superobject on Wikipedia/Dictionary |
| List of items | List of Superitems on Acmecorp2 |
| Overview of a product or feature | Overview of Superproduct |
| GitHub home page of 3rd party software | Acmesoftware GitHub page |
# Images
| When referring to | Write |
|---|---|
| A screenshot | Screenshot of Acmecontent |
| A diagram | Diagram of Acmearchitecture |
| A picture | Picture of Acmepicture |
| A logo | Logo of Acmecorp |
| A portrait | Portrait of Acmeview |
| A painting | Painting of Acmefruitbasket |