The damage of examples

September 1, 2014

Topics: Accessibility, Web Development.

These are lies we tell:

“This is just an example.”

“This is a demo, not for use as production code.”

No, it’s not. You’re wrong. It may not be code you, the author, would use in production. But as soon as you published it, the likelihood that it will become production code in somebody else’s project skyrockets.

And this is inevitably damaging. These examples can be horrible in many ways – reliability, portability, security – and accessibility. In a surprising turn, I’ll be talking about the accessibility problem.

I understand what the problem is – when we write an example, we want it to be a concise demonstration of the principle we’re illustrating, so we strip out the encumbrances like escaping, sanitizing, and elaborations that aren’t central to the point we want to make. Labels and ARIA attributes are definitely in the list of things that make the code more complex.

I don’t have a problem with this.

But when we don’t also include a version of the code that does include everything that makes the code safe and accessible, we act irresponsibly.

Accessibility is a feature that’s far too frequently omitted from examples, unless the examples in question are about accessibility. Fine. Accessibility related attributes are verbose, and may distract from the point in question. But they’re also crucial to the usability of the code for many people. Inviting the propagation of inaccessible code is a shame, and is one of the reasons that the accessibility battle is so difficult.

How about an example?

I’ve seen this many times, but I’m not doing this to call out any particular individuals; this is a systematic problem, and is at its worst in some of the large tutorial oriented sites.

Let’s take a look at an example provided by that stellar example of web programming education, W3 Schools. W3 Schools isn’t exactly known for the highest quality of information — but they are definitely one of the first results you’re likely to find for many basic questions; so this is a place to look to find massively propagated issues.

PHP 5 Complete Form Example

The tutorial is about how to keep variables in a form after the form is submitted. Obviously, accessibility isn’t the focus of the tutorial. Fair enough.

But knowing people’s habits, what’s going to be taken away from this by a person who’s just trying to learn what to do? This code:

Name: <input type="text" name="name" value="<?php echo 

E-mail: <input type="text" name="email" value="<?php echo $email;?>">

Website: <input type="text" name="website" value="<?php echo $website;?>">

Comment: <textarea name="comment" rows="5" cols="40"><?php echo $comment;?></textarea>

<input type="radio" name="gender"
<?php if (isset($gender) && $gender=="female") echo "checked";?>
<input type="radio" name="gender"
<?php if (isset($gender) && $gender=="male") echo "checked";?>

This isn’t the full code – so maybe the full, working code example includes some labels. No. No, it doesn’t.

This is an extremely simple form; but every person who copies this into a project because they don’t know any better is creating an inaccessible experience on that project.

What’s your point?

If you’re going to teach somebody about the web, and how to create good products, that means making sure that every example gives the opportunity to do something right — not just a test scenario, to prove that something works in general terms. Education needs to be integrated: it should never be an option to learn how to do something incorrectly. Whatever the specific issue that’s being addressed, the examples used must not simplify to the point that they introduce new problems.

Have something to contribute?

« Read my Comment Policy

12 Comments to “The damage of examples”

  1. Thanks for sharing, Jens! The link to WTF A11y in your Google Plus thread is very interesting.

  2. One of your readers shared this with me after I posted a similar note on Google+ [1]—I couldn’t agree more. What I like to see in particular is the bigger companies, like Google, Facebook, Twitter, &c., to step it up.


  3. @Ulrich

    Sorry – your comment got flagged by Akismet and I missed it!

    Yes, that’s exactly my point – the examples need to and should be simplified in order to educate readily; and having a series of snippets that illustrate simple cases is fine. But they need to be accompanied by legitimate examples that flesh out the necessary code, in addition to the minimal version.

    It’s particularly concerning, as Wojtek mentions, when the tutorial is targeted at beginners — this specific example is a great case study for that circumstance. This is a very basic task, and it’s more than reasonable to assume that the reader of the tutorial knows little about internationalization, accessibility, and security; so omitting all of those from every example is irresponsible.

  4. Very true. I actually ran into the same problem one day after this post has been published (

    It is extremely important for authors to realise that even when they focus on a different aspect of the code (e.g. PHP or JS functionality), they still must take care of accessibility and following best practices as a whole, as that lays at the root of any good quality code.

    There have been a plenty of cases when people copying code samples without modifying them broke a fair part of websites, such as when most popular meta viewport snippet at the dawn of RWD disabled user zooming, or when developers weren’t adding default :focus styles in Eric Meyer’s reset CSS.

    For that reason, especially if a tutorial is aimed to beginners, I think we should be very cautious to avoid spreading antipatterns.

  5. Mobility issues can be almost anything, but at their most common and damaging it’s a lack of support for keyboard-only use, and is rampant. This is potentially one of the largest areas of accessibility concern.

    The problem with the divided concept is that it presumes that disability is binary – either you’re sighted, and can use the sighted site, or that you’re not sighted, and need the audio site. But in the real world, disability is not even close to binary. A person with low vision may prefer the visual experience, but if it’s not zoomable or, or doesn’t offer keyboard accessibility or large buttons, then it’s a terrible user experience.

    Offering a version of a site that optimizes the audio experience is fine – but it’s not a substitution for having a primary site that’s accessible. That site still needs to do everything it can to be accessible; the audio version would only be an enhanced version for the visually impaired. As an alternative, however, it’s a travesty.

  6. Thanks for your reply Joe. I see where you’re coming from, but I disagree because as politically in-correct as it sounds, “not being able to see” is not equal to “being able to see”. My idea is not to create another domain name for the visually impaired but rather a first link in the main site that leads you to an audio friendly version of the site you just entered. As far as I can tell, the internet (for now) only provides information through sight and sound. Not sure why we’d need another site for the mobility-impaired, that’s more of a hardware issue which I’m pretty sure many people are working on, which will allow users to navigate the net without needing the keyboard or mouse. Whereas it’d be ideal for a visual website to be audio friendly, I genuinely think audio-friendly sites would be a lot more enjoyable/fairer for the visually impaired.

  7. “require companies to mirror their information on accessible websites. One site is created for the eyes, the other site needs to be created for the ears.”

    What you’re describing here is the web accessibility equivalent of the “Separate but Equal” doctrine, the racist policy of segregation. The problem with this concept is that the simple fact of providing a separate resource is inherently inequal.

    Consider the process of gaining access to an alternate site for accessible YouTube videos.

    You do a Google search; and it brings up the result. Which result does it bring up first? Can you clearly identify which resource you’re going to visit, so that you don’t go to the wrong site? The wrong site will be totally inaccessible, of course, since only the “accessible” site needs to consider accessibility at all, so if you end up there, you’re pretty much screwed. And do you need to have individual sites for each variety of disability, as well, so your search results need to direct you to the sighted site, the audio site, the hearing impaired site, the deaf-blind site, the mobility-impaired site, and the “man, I’m so drunk” site?

    Separate but equal is an unworkable premise; segregation ensures inequality.

  8. Completely agree. Whomever develops code should only publish and therefore “teach” their code, once it is 100% correct/complete.

    I’m trying to make a WordPress site (that someone else coded), accessible and it is proving to be a nightmare! YouTube players should be accessible wherever they’re embedded and JAWS should recognize a YouTube video when it comes across it! WCAG by now should not request websites to be accessible, but rather require companies to mirror their information on accessible websites. One site is created for the eyes, the other site needs to be created for the ears.

  9. I agree to an extent but goal of the tutorial is to show how to use PHP to do this one task. It is easier to learn something with it broken down into smaller parts.

    There should be a mention that i18n,security and a11y have been excluded for the simplicity of the example.

    There was even a discussion about i18n for codex examples.

  10. This is also part of the general idea companies seem to have about accessibility: that it’s a “specialty” that doesn’t fit with their “target group” of users.

    Code examples not showing security and accessibility is just the other side of thinking those things are “extras”.