Chapter 03 Effective HTML

Have you noticed that a lot of websites are bad?

In the rest of the chapter, we’ll look at these issues in more detail and see how effective HTML can help us develop better websites. However, we should first note that HTML is not a panacea. If you care about machine readability, or human readability, or page weight, the most important thing to do is testing. Test manually. Test automatically. Test with screenreaders, test with a keyboard, test on different browsers and hardware, run linters (while coding and/or in CI).

So where does HTML and the s-word come in?

Easy. Writing good, spec-compliant HTML lets browsers do a bunch of work for you. Furthermore, even when they don’t, it makes it easier to write scripts that do. Fewer issues will be found during testing and you can release faster. When issues do come up, you can often fix them more easily by refactoring HTML as opposed to heaping JavaScript and ARIA attributes over everything.

Knowing HTML well might not absolve you from doing your job, but it makes it a lot easier.

“But I already know HTML well.” Maybe you do. But many people underestimate how sophisticated HTML is. Indeed, it’s very easy (and sometimes acceptable) to produce mediocre HTML that seems to work, and many websites settle with seeming to work. But better websites are possible, and anyone can learn HTML to the level of making websites that actually work.

While programming code is described as spaghetti when it’s not well organized, the food of choice for messy markup is soup^[3].

HTML can turn into soup in a variety of ways, usually due to a disregard for or misunderstanding of best practice or due to an excess of layers between the developer and the HTML.

The best-known kind of messy HTML is <div> soup. When developers fall back on the generic <div> and <span> elements instead of more meaningful tags, we either degrade the quality of our websites or create more work for ourselves — probably both.

For example, instead of adding a button using the dedicated <button> element, a <div> element might have a click event listener added to it.

Why might a developer do this, when the <button> element is right there? There could be a few reasons:

It’s absolutely possible to implement this button, and indeed most kinds of UI, using nothing but <div>. However, it makes the job harder.

There are two main issues with this button:

Let’s fix that:

Of course, these are both easy fixes but they’re things you have to remember. It’s not obvious from the HTML source that this is a button, making the source harder to read and the absence of these attributes harder to spot. Furthermore, even if you always remember to add the correct attributes and JavaScript — and yes, if you’re making almost anything more complex than a button, you will need a lot of JavaScript — you’ve made your HTML less readable for little reason. The source code of pages with div soup is difficult to edit and debug.

We often don’t remember to look out for these types of UX and accessibility bugs. F5-Driven Development is the way most of us write HTML: write something, Alt-Tab to the browser to see if it works, and go back to edit. It’s a fast and enjoyable way to build things, but it means that during most of development, developers are biased towards their own UI needs, and users (who might use websites differently) become an afterthought. However, if we use HTML effectively, we can catch many of these issues before they ever occur, even before testing.

Given all this, why are so many developers writing div soup? There is a tendency to understate the sophistication of HTML.

Instead, learn the meaning of every tag and consider each another tool in your tool chest. (With the 113 elements currently defined in the spec, it’s more of a tool shed).

Markdown soup is the lesser known sibling of <div> soup. This is the result of web developers limiting themselves to the set of elements that the Markdown language provides shorthand for, even when these elements are incorrect. Consider the following example of an IEEE-style citation:

Here, <em> is used because it’s the only Markdown element that is presented in italics by default. This indicates that the book title is being stressed, but the purpose is to mark it as the title of a work. HTML has the <cite> element that’s intended for this exact purpose.

Furthermore, even though this is a numbered list perfect for the <ol> element, which Markdown supports, plain text is used for the reference numbers instead. Why could this be? The IEEE citation style requires that these numbers are presented in square brackets. This could be achieved on an <ol> with CSS, but Markdown doesn’t have a way to add a class to elements meaning the square brackets would apply to all ordered lists.

Don’t shy away from using embedded HTML in Markdown. For larger sites, also consider Markdown extensions.

You can also use custom processors to produce extra-detailed HTML instead of writing it by hand:

“Yeah! Down with <div>! It’s time to use the full power of HTML5!”

Be careful.

Elements like <section>, <article>, <nav>, <header>, <footer>, <figure> have become a sort of shorthand for HTML. Developers may sprinkle them generously and haphazardly over <div> soup. This is not an improvement, and can in fact make a website worse. By using these elements, a page makes false promises, like <article> elements being self-contained, reusable entities, to clients like browsers, search engines and scrapers that can’t know better.

Most HTML isn’t this much of a mess, but it’s far too common for <section> and <article> to be used as a drop-in replacement <div> instead of adding useful information. To avoid this:

You might have noticed how we’ve avoided the use of the word “semantic” so far, partly because many people associate it with annoying pedantic colleagues (couldn’t be us!), and partly because it has multiple meanings, only one of which we care about.

We’re not really about the “Semantic Web”.

The "Semantic Web" was a vision of a system that could both express any kind of human knowledge, and be useful for computing. It planned to achieve this using ontologies, repositories of schemas like "person", "movie" and "species" and relations like "named", "part of" and "created by".

The problem with this vision is that information on the Web rarely fits into neat categories. Because no single ontology can be defined that encapsulates all kinds of information one might wish to publish on the Web, Semantic Web systems need to be pluggable with different schemas. In turn, a Semantic Web client, in order to do something useful with an arbitrary piece of HTML, needs to be able to parse these schemas, which means we need to define a standard machine-readable format for ontologies. But a single format couldn’t express every kind of object and relation…​ It’s turtles all the way down.

In practice, most implementations stop at the topmost turtle. Ontologies are defined in natural language, and clients are hardcoded to support a fixed set of schemas. The requirement for prior agreement between server and client means this technology does not have the generality of the Web, and for most use cases, you might as well define a JSON API.

Instead of extensibility through custom namespaces, HTML is extensible through its flexibility — both its tolerance for errors and its well-defined extension points like classes and data- attributes. These affordances let us embed metadata in it without native support. They all have the possibility of name collisions, but fragility and messiness is ultimately unavoidable for a generalized human information exchange language. Tag and attribute names in such a language are not identifiers for behavior — like function names in a programing language — but words with well-understood meanings. No amount of namespacing can make fetch happen, and developers should be able to deal with that. Embrace the mess and let go of your schemas. A flexible format — not an infinity of namespaces with URLs pointing to nothing — is “software design on the scale of decades”.

This is a necessarily reductive explanation of the Semantic Web, a field that we’ve described in past tense even though it continues to have some practical use. The reason it doesn’t matter to us is because the Semantic Web has nothing to do with semantic HTML.

Semantic HTML has no ambitions of robotic agents navigating information and helping us make connections and discoveries. It’s actually quite mundane: don’t break the web.

Telling people to "use semantic HTML" instead of "read the spec" has led to a lot of people guessing at the meaning of tags — "`looks pretty semantic to me!" — instead of engaging with the spec.

I think even “meaningful” is too lofty. Instead, I recommend talking about, and writing, conformant HTML. Use the elements to the full extent provided by the HTML specification, and let the software take from it whatever meaning they can.

Speaking of assistive technologies, by the way…​

Throughout this chapter, we’ve gestured at potential accessibility benefits to be had from effective HTML.

It’s true that all else being equal, an app that makes full use of HTML will be more accessible than one that is made of soup. However, HTML is not a panacea. Even the adage that HTML is “accessible by default” is a bit misleading.

If you use simple HTML strictly as recommended by the spec, you are unlikely to run into accessibility bugs (though it does happen, because this is web development). Problems often arise when we try to implement controls that aren’t built into HTML. Sometimes, JavaScript is necessary to implement a UI control in an accessible manner (that is, in a way that supports all required keyboard interaction and presenting state to assistive tools). Clever "tricks" to implement controls in only HTML/CSS are fun, but often not practical. Take the following code, which uses radio buttons and CSS hacks to create something that resembles tabs:

This code will “work.” Clicking on the tabs will change the content displayed, and without a single line of JavaScript. Unfortunately, tabs have requirements beyond clicking to change content. This implementation has many missing features that will lead to user confusion and frustration, as well as some undesirable behaviors. From the ARIA Authoring Practices Guide on tabs:

It turns out that fulfilling all of these requirements takes a lot of code. Some of the ARIA attributes can be added directly in HTML, but they are repetitive and others (like aria-selected) need to be set through JavaScript since they are dynamic. The keyboard interactions can be error-prone too. It’s not impossible to make a good tab set implementation. However, it’s difficult to trust that a new implementation will work in all environments, since most of us have limited access to testing devices. This is why it’s often recommended to use established libraries for UI interactions instead of rolling your own.

Before adding a dependency, however, let’s reconsider our design. Does the information really need to be presented as tabs? Sometimes the answer is yes — we used dummy text in our code example, so we can’t tell — but if not, a sequence of details disclosures fulfills a very similar purpose.

Compromising UX just to avoid JavaScript is bad development. At the same time, the possibilities and constraints of the platform should be considered while designing interfaces. It might be possible to achieve an equal (or better!) quality of UX while allowing for a simpler and more robust implementation. But when it’s not, we shouldn’t try to stuff every problem into an HTML box.

Hypermedia systems perform best with human-operated clients. However, machine-readable information can be embedded into HTML pages through a variety of extension mechanisms:

These mechanisms are fairly unstructured (as per earlier discussion on Semantic Web schematamania), but structure can be imposed upon them if needed. One standard for including structured data in HTML is microformats. Microformats use classes to mark certain elements as containing information to be extracted. The microformats2 standard uses five kinds of classes:

There are also conventions for extracting common properties like name, URL and photo without needing classes for each property.

By adding these classes into the HTML representation of an object, we allow the properties of the object to be recovered from the HTML. For example, this simple HTML:

can be parsed into this JSON-like structure:

We can see microformats in action by looking back at how we can mark up the reference list we mentioned earlier in this example. Using a variety of properties and nested objects, we can mark up every bit of information about the work being cited in a machine-readable way:

This can be parsed into a JSON-like structure, as follows:

In this example, Microformats and the extensibility of HTML proved quite useful. However, embedding data in HTML is hardly appropriate for every use case. Your human-facing and machine-facing interfaces may end up being limited by each other. It’s often the best option to define a JSON data API separate from your HTML, which will be discussed later in this book.

Unfortunately, a full HTML tutorial is way out of scope for one chapter of this book. Here are some resources you can check out if you’d like to invest in your HTML knowledge: