Accessibility In Programming Tutorials, Guides & Documentation
Programming is unnecessarily unfriendly to beginners. We can make it better through simple optimizations. This is the First of a Series of blog posts where I’ll be exploring that!
I’ve been learning programming very steadily for the last year, and there’s something that bothers me a lot: There is an unnecessarily steep learning curve for beginners — especially people who are self-taught! A learning curve makes sense — programming is a very technical, complex & intricate craft. It’s a very big skillset to develop, and it takes a long time. But we’re making it unnecessarily hard for our new people — and on top of that, it’s an accessibility issue*.
Two common problems that tend to come up for new developers: many tutorials don’t define their terms; and almost everything seems to have lots of unstated dependencies.
As a beginner, this means I have to go through a never-ending rabbit hole of googling and looking things up just to try to learn or start this one basic new thing**.
One of my favorite pieces of programming wisdom is The Zen of Python. This line in particular: “Explicit is Better than Implicit”. There are a couple of easy ways that we can apply the “Explicit is Better than Implicit” guideline.
- Hyperlinks: It’s so easy to make a Hyperlink (like I just did for The Zen of Python) — that reduces the amount of hunting your readers have to do.
- Footnotes: A great example of using Footnotes is this Intro to Functional Programming. Every other (functional programming) tutorial I’ve attempted to read just gives me all these strange terms, out of context. Additionally, when I google them, there’s a lack of consensus about what they do & don’t mean. Most of that information is irrelevant to me as a beginner who’s new to functional programming. I would need to be a more experienced developer before I could take advantage of most Functional Programming Tutorials. It’s counter-productive!
- Guide to Contributing for Newcomers: Contributing to many OSS (Open Source Software) projects is a Nightmare. VLC does a Pretty Good Job of this, so does Gnome. As a beginner, you’re often looking at code that’s beyond the level you’ve worked at, and you have to go through a very Large Code Base to understand what’s what. Wouldn’t it be much better for all of us if there was some magical document showing people where to go? — It’s like having Street Signs (or GPS)!
- Too Long, Didn’t Read: tl;dr statements first appeared in the early 2000’s, as a snarky response to overly long posts! They can be a great way to succinctly present the most important points of a tutorial or section. A more elegant approach would be Concept (at the Top of a tutorial/section); Summary (at the Bottom of a tutorial/section)
There’s lots of other options to explore too! I don’t have all the answers, but I think with some experimenting, we can make the programming world better for everyone — newcomers especially!!
tl;dr: Put in some Hyperlinks & Footnotes. Make guides for contributing to Open Source Software. Use tldr statements.
Explicit Is Better Than Implicit! :)
Footnotes:
*What do I mean by that? A lot of programmers are neuroatypical. Many of us have learning disabilities or other disorders that make programming uniquely challenging.
(Tangentially: Some people prefer to use neurodivergent. There’s debate about whether they are synonymous or dichotomous — well outside the context of this post!)
- *This is called Yak shaving. A definition: “Yak Shaving is what you are doing when you’re doing some stupid, fiddly little task that bears no obvious relationship to what you’re supposed to be working on, but yet a chain of twelve causal relations links what you’re doing to the original meta-task.”
Cross-Posted from: Luna Codes — Reflections on Coding & IT
