3 tips to create accessible HTML documents
Create HTML pages and files that everyone can read, regardless of access.
This Thursday, May 16, 2024 is Global Accessibility Awareness Day. Accessibility provides access to communication in all its forms. I would argue that if you create digital communication such as websites, it’s even more critical that you create accessible content that everyone can access. If our audience cannot read or otherwise access the content we create, then we have failed as technical communicators.
HTML provides several methods that you can use to create accessible content. Here are three common ways that you can ensure everyone can access your online content:
1. Alternative text for images
HTML pages have supported images since the very beginning. The <img> tag references an image, such as a JPG photo or PNG image or SVG logo. When including images in your documents, don’t forget to use the alt= attribute to provide alternate text for your audience. This alternative text will be used by screen readers and other assistive technology to provide a description of the image for those who cannot see it.
For example, let’s say you managed a website for a software company, and you wanted to include a screenshot of a user installing the software on a computer. You might use this <img> reference for the photo:
<img src="/images/photos/789034566-asset-213.jpg"
alt="photo of a user installing the software on a computer">In another example, you might reference the company logo in the web page header like this:
<img src="/images/logos/logo-web-header.svg"
alt="logo of the Acme company">However, it’s important that your alternative text is actually descriptive of the image. Don’t skip the alternative text (it’s required, anyway). Also avoid a trivial description that doesn’t adequately describe the image. Let’s go back to the photo of the user installing the software on a computer; the brief one-sentence alternative text provides a “word picture” of what the image is meant to represent. But this one-word alternative text doesn’t describe the image with any meaningful detail:
<img src="/images/photos/789034566-asset-213.jpg"
alt="photo">A website visitor who relied on a screen reader would not understand what this image was meant to represent. The name of the file doesn’t suggest what the photo is about, either.
Best practice: Provide a brief sentence that describes the image.
2. Semantic markup
In the early days of the web, authors created web pages using very simple markup tags. In those days, it was typical to divide a page using <div> tags - such as a simple page with a header, main body, and footer - like this:
<div class="hdr">
<img src="/images/logos/logo-web-header.svg"
alt="logo of the Acme company">
<div class="navbar">
<a href="/">Home</a> <a href="/about/">About us</a>
</div>
</div>
<div class="bdy">
...
</div>
<div class="ftr">
<p>Neque porro quisquam est qui dolorem.</p>
<p>Copyright 2006 Acme Corp.</p>
</div>However, <div> carries no meaning by itself; the class= attribute is only useful with stylesheets. This web page structure provides no information to someone with limited vision, or for some other reason requires a screen reader. Every time this user visits the website, their screen reader will have no option but to read the entire contents of the page to them.
In 2008, HTML version 5 introduced semantic markup, which provided meaning to the tags that structured an HTML document. Most web pages have a header, main body, and footer, so HTML 5 provided structures to do that: <header>, <main>, and <footer>. HTML 5 also included other semantic markup such as <article> for body content that might be an article or other information item, <section> for larger divisions of a page, and <nav> to provide navigation links.
These semantic tags could be used anywhere within a web page; the <body> of a document might have a header, main body, and footer - but <article> content might have these, as well.
The semantic markup also meant that screen readers could help users navigate a web page. Depending on the software, the screen reader might announce “header” when it encounters a page header, then start reading the header content. The user can skip ahead with a hotkey to get to the next major section, such as the main body - which the software might announce briefly as “body” before reading it aloud.
Structuring an HTML document using semantic markup provides a more logical organization to the web page. For example, we might rewrite the web page sample (above) using HTML 5 semantic tags, like this:
<header>
<img src="/images/logos/logo-web-header.svg"
alt="logo of the Acme company">
<nav>
<a href="/">Home</a> <a href="/about/">About us</a>
</nav>
</header>
<main>
...
</main>
<footer>
<p>Neque porro quisquam est qui dolorem.</p>
<p>Copyright 2006 Acme Corp.</p>
</footer>Best practice: If you are still using <div> to structure your web pages, start learning HTML 5 semantic markup now. For example, W3 Schools provides a good overview of HTML semantic markup that you can use to learn on your own.
3. Captions in figures
HTML 5 didn’t just add semantic markup to provide structure to a document. Many of the semantic tags also enhance accessibility. One important feature is the <figure> block element, which acts as a container for images, charts, graphs, and data displays.
Figures can include <figcaption> as an optional caption, but I recommend you include it where you can. A figure caption should describe the image in a complementary way to the alternative text. Consider the alternative text to provide the description and the caption to provide the context for the image.
For example, let’s say you are writing a year-end report as an HTML document, and you want to include a photo of all the developers at the annual community gathering. You might include this image in an HTML document using <figure> and <figcaption> like this:
<figure>
<img src="/photos/community/everyone.jpg"
alt="photo of the developers at the 2024 community gathering">
<figcaption>We celebrated our developer community with a special event</figcaption>
</figure>Note that the alternative text describes the photo itself, while the figure caption provides additional contextual information about the photo.
Best practice: If you need to include a data display as a block element, use <figure> and provide a description using <figcaption>.
Jim Hall is an open source software advocate and technical writer. At work, Jim is CEO of Hallmentum, an IT executive consulting company that provides hands-on IT Leadership training, workshops, and coaching.