Symbolic Forest

Recently I added Aria Salvatrice to the list of links over in the menu, because I’m always looking to find new interesting regular reads, especially ones that use old-fashioned blogging. In this case, I found myself reading one of its posts which I absolutely found myself nodding along to. It was: Video Tutorials Considered Harmful, about how videos are a much worse venue for learning a technical topic than written documentation.

In general, I agree wholeheartedly with this, with an exception that I’ll come to below. Aria gets to what I think is the nub of the problem: that for some people, with some forms of neurodiversity, it’s really, really hard to focus on the video enough to take it in properly and digest it, and far too easy to get distracted. Your mind just wanders off, in a way that doesn’t happen—or at least not as much—if you’re reading a written text. All of a sudden, you realise that your head has been completely elsewhere for the last five minutes, and you have no idea what you’re watching any more.

What I find strange about this in the tech world, though, is that neurodiversity is hardly rare among software developers and similar professions. This is definitely something that has come up with my current colleagues more than once: the fact that a good proportion of us have this same problem: if we start watching an explanatory video, our minds wander off. All of a sudden, we’ve missed a huge chunk of everything and have no idea where we are. If this is so common among tech practitioners, why are these types of video common in the tech world?

The Plain People of the Internet: But don’t you yourself there have your own YouTube channel?

Yes, I do, but I don’t use it to try to teach you things. Not technical things, at any rate. They are turned into text and posted here, or wherever is most relevant. I don’t create videos of myself lecturing to camera.

That brings me onto another aspect of this, though: the difference between good and bad videos, and how bad videos make things ten times worse. Now, I haven’t posted anything on YouTube for quite a long time, but that’s largely because of the effort involved in making a video that I think is good enough to put out there. In short: I edit. I don’t just live-record a video of me doing something, chat as I go along and upload it; instead I edit. I cut it down, I write a narration, I record and edit that and stitch the whole thing together so that a project that took me several days in real life becomes a ten-minute video. In the sort of tech videos I’m talking about, this often doesn’t happen. Aria writes about this in its original post:

[M]ost video is entirely improvised, and almost never cut to remove wasted time. People’s thoughts meander. Their explanations take five sentences to convey what a single one could have said with more clarity. They wait on software to load, and make you wait along. They perform a repetitive task six times, and make you watch it six times, they perform a repetitive task six times, and make you watch it six times, they perform a repetitive task six times, and make you watch it six times […] And while it is easy to skip repetitive text, it is difficult to know where to skip ahead in a video.

Because, actually editing that down, writing a script, making it concise and informative is itself a skill, a hard one to learn. It’s difficult work. Much easier to just video a stream-of-consciousness ramble and push the whole thing up to the Internet unedited. And that’s why people do it: it’s similarly easier than writing good documentation. Knowing how to explain something you know well, to someone who knows little about it, is also a surprisingly difficult skill that a lot of people don’t even realise they don’t have.

This doesn’t necessarily apply with videos demonstrating physical things that are much harder to describe than to show, by they way. Crafting tutorials, for example, such as How To Crochet A Magic Ring. Even in that case, though, the good ones are carefully edited, brief, clear and concise.

In short, what I’m saying is that video has taken over (to some extent) from written documentation because if you’re willing to accept low quality, it’s much easier to produce, even if the results are worthless. It’s inevitably lower-quality, though, because of all the flaws in the format mentioned in Aria’s piece, such as lack of searchability. It’s accidentally low quality because if the creators put the effort in to make it good, it would take as much or more effort than writing good textual documentation takes. Those flaws can be fixed by putting the effort in and learning to skills to make a good video; but the inherent flaws of the format can’t be changed. Better all round to produce written documentation from the start.

Keyword noise: documentation, video, learning, coding, software, software development.