<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Andrés Villarreal on Medium]]></title>
        <description><![CDATA[Stories by Andrés Villarreal on Medium]]></description>
        <link>https://medium.com/@andrezrv?source=rss-ff556d3415e6------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*e8R-14t7z_c4HJ57gD3wUw.jpeg</url>
            <title>Stories by Andrés Villarreal on Medium</title>
            <link>https://medium.com/@andrezrv?source=rss-ff556d3415e6------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 22:55:47 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@andrezrv/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Accessible Code: Thoughts On Writing For Developers (Part 1)]]></title>
            <link>https://medium.com/@andrezrv/accessible-code-thoughts-on-writing-for-developers-part-1-58802f983d5b?source=rss-ff556d3415e6------2</link>
            <guid isPermaLink="false">https://medium.com/p/58802f983d5b</guid>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[web-accessibility]]></category>
            <category><![CDATA[coding-best-practices]]></category>
            <dc:creator><![CDATA[Andrés Villarreal]]></dc:creator>
            <pubDate>Thu, 27 Aug 2026 13:00:58 GMT</pubDate>
            <atom:updated>2026-09-08T18:48:29.287Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*JoRtz2fUbxxByuqW.jpg" /></figure><p><strong><em>Note:</em></strong><em> this is a revised version of an article originally published in May 2014. While I don’t completely agree with what I wrote 12 years ago, I still find most of the article challenging and valuable. So, instead of adjusting it to how I think today, this revised version expands on the main ideas and, I think, serves as a window to how I used to think in the past.</em></p><blockquote><em>Programs must be written for people to read, and only incidentally for machines.<br>– Harold Abelson and Gerald Jay Sussman</em></blockquote><p>Writing accessible code isn’t just about the people using whatever you built — it’s about everyone who has to read, maintain, or build on your work after you.</p><p>A while back I read an interview with Kate Swaffer, an Australian blogger and dementia advocate, about her experience using WordPress while living with dementia. One detail stuck with me: she suggested that WordPress’s tutorials and help resources could be improved by breaking them down into more basic steps, the kind of thing an experienced user takes for granted, but that makes a real difference for someone who can’t rely on things staying in memory from one session to the next.</p><p>Reading that made me think about a number of things we leave aside in our daily work that could push people away from it, or make it harder than it needs to be for them. Sometimes we choose to do that, and sometimes we’re just not thinking about who’s on the other side. Her blog, <a href="https://kateswaffer.com/">Creating Life With Words</a>, is worth reading; <a href="https://torquemag.io/2014/05/memory-bank-blogging-with-dementia/">her interview with Torque</a> is where I first came across her.</p><p>Our website might not be well prepared for screen readers, or might not work consistently across browsers. Our CSS might be missing line breaks, or our JavaScript minified without leaving the source at hand. We often prefer spending our time writing more code instead of documenting what we already have. Sometimes we use unnecessarily technical language in blog posts without a real need to. The admin of a community site might make decisions that favor some users over others without meaning to. There’s a long list of things we can do, mostly without noticing, that push people away.</p><p>We can’t possibly account for everyone; that would be an impossible standard. People are different from each other, and that’s what keeps things interesting, for better or worse. But I think we can try to know our audience, at least as well as we’re able to. And I think the same idea applies to programming: writing accessible code isn’t optional just because your work isn’t visible to end users.</p><h3>Code Problems</h3><p>Let’s say you’re a senior engineer, and you’ve recently started working with a team where your colleagues are far less experienced than you. They still have best practices to learn, coding guidelines to follow, programming patterns to internalize, and a lot of documentation to write. Let’s also say you wrote a library they need to use to get their work done. After a reasonable amount of time, the work still isn’t done. They don’t seem to understand what you built, the reasoning behind it, how your classes and methods are supposed to work together.</p><p>You’re surprised. The full documentation, of course, is easily available to them. There are comments in the code. Any experienced engineer would understand how to use it. That’s the problem, though: they’re not experienced, at least not yet. Is that really their fault?</p><p>At this point you’re considering your options. You could blame them, tell yourself they’re just not capable, and consider your part of the job done. You could try to teach them and help them get better, knowing it’ll take time. Or you could revisit your code and rewrite parts of it, trading some optimization for something more approachable at their current level.</p><p>This was never a documentation problem. The missing part was actually the connection between what the problem needed and how your code addressed it, a connection buried under layers of complexity they haven’t learned to see through yet. A developer who can’t follow that connection can’t really operate on the code, no matter how many comments surround it, and that’s a common trait in junior engineers. They need time and experience to learn to see the full picture through more complex scenarios.</p><p>In 1985, Peter Naur argued that <em>“the primary aim of programming is […] to have the programmers build theories”</em> of the problem being solved, not just to produce a working program, and that this theory lives in the people who built it far more than it lives in the code itself, which is at best a partial, lossy trace of it.</p><p>That’s a more academic way of saying that code by itself is not as valuable as its purpose. The theory behind it, carried by the people who hold it, matters just as much as whatever ends up written down. It’s our responsibility to keep that theory reachable and accessible to anyone who comes in contact with it.</p><h3>What Can Be Done</h3><p>If you’re anywhere close to being wise, you won’t blame people for not being capable of doing what you can indeed do. Someone with little experience today has plenty of room to grow, so writing them off just because they haven’t caught up to your level doesn’t help anyone.</p><p>Talking things through with your teammates helps, but it takes time your team may not have. Businesses often want something shipped, not something shipped well, and won’t always fund the extra hours a careful, patient handoff requires.</p><p>When that’s the case, and your code stays out of reach for the team, they’ll usually find their own way around it: reinventing, less effectively, something you’d already solved. What they come up with might be quick and full of flaws, or it might turn into a rework that takes even longer than the original did. Either way, your boss ends up just as frustrated, and your own work sits unused in the meantime.</p><p>There’s a third option, beyond blaming them or waiting on lessons that may never come: you can rewrite parts of your own code to meet your team where they actually are. Say you built a plugin using a chain of decorator classes, and your team is more at home with procedural code; a single function hooked into the right filter can often do the same job in a shape they already recognize. Or say the MVC pattern is unfamiliar to them: template files paired with helper functions, the same structure WordPress themes have used for years, can stand in for a controller layer. You’ll find plenty of cases like these once you start looking for them.</p><p>There’s a whole framework built around this same notion now, usually discussed under the label “cognitive load”: the general idea that some popular clean-code conventions, like keeping every method under fifteen lines or splitting logic across many small classes, can sometimes add more mental overhead than they remove, since the reader has to hold more separate pieces in mind at once instead of fewer. I’m not going to get into the full weight of that argument here, or into how any of it shifts once AI tools are reading and writing code alongside us; that’s a much bigger conversation than this piece can hold. But if this idea resonates with you, it’s worth following further on your own.</p><h3>What Accessible Code Actually Looks Like</h3><p>Some people might see that last approach as “toning down” their abilities, or encouraging bad practices, or limiting how much developers get to grow. I can understand that reaction, but I don’t think it’s that simple. I think a developer needs to know the people they’re working with, the closer the better, and what those people are actually able to do with a specific piece of code. It’s about thinking of accessibility as a whole, because code should be accessible too.</p><p>That’s one of the reasons WordPress has succeeded the way it has: most of its code is readable and understandable even to developers with relatively little experience. That doesn’t mean you should write simplistic or limited code. It means you should write code that’s genuinely accessible, smart enough to be effective, and simple enough to be usable by the people who are going to work with it.</p><p>And here’s the real point in all of this: no matter how experienced you are, or how good you think your code is, if it isn’t accessible to the people who need to interact with it, even people who know less than you, that’s a sign it still needs work.</p><p>At the end of the day, what separates a good developer from everyone else is whether they’re genuinely thinking about the people around them, or only about themselves.</p><h3>Further Reading</h3><ul><li>Abelson, H., &amp; Sussman, G. J. (1984). <a href="https://mitp-content-server.mit.edu/books/content/sectbyfn/books_pres_0/6515/sicp.zip/sicp.html"><em>Structure and interpretation of computer programs</em></a>. MIT Press.</li><li>Naur, P. (1985). <a href="https://pages.cs.wisc.edu/~remzi/Naur.pdf">Programming as theory building</a>. <em>Microprocessing and Microprogramming, 15</em>(5), 253–261.</li><li>Zakirullin, A. (n.d.). <a href="https://minds.md/zakirullin/cognitive"><em>Cognitive load is what matters</em></a>.</li></ul><p><em>Originally published at </em><a href="https://andrezrv.com/2026/08/27/thoughts-writing-accesible-code-part-1/"><em>https://andrezrv.com</em></a><em> on August 27, 2026.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=58802f983d5b" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>