April 22, 2021

I teach my sister how to code, she teaches me how to teach part 1

Explaining things is all about abstraction, and so is programming. So, why do so many developers (myself included) struggle to communicate with non-tech people? I tried to answer this question by walking in a teacher’s shoes for a day.


This post is part of a series:


I recently had a discussion with a client of mine about a feature to be developed on his e-commerce. I wanted to make him understand how configurable products on Magento work in deep, but I couldn’t explain. The more I added details the more complicated it seemed, it was extremely frustrating

I realized that the ability to communicate is very important to any developer, especially a freelancer. And despite my best efforts, what I do is not enough.

I turned to an expert: my little sister

My sister teaches math and physics at school. She has the amazing ability to explain complex things in simple words and make them interesting.

"The Man Who Shot Liberty Valance" James Stewart in “The Man Who Shot Liberty Valance” John Ford 1962

Since she would love learn programming, she proposed that I teach her. This way she can learn something new and at the same time show me the right approach to teaching.

Chapter 1. What the hell does it mean programming

This part went very smoothly, not least because she has a school background. She quickly understood what client side and server side language means and how the instructions are interpreted. We chose javascript not only because it is my main language, but also because it can be interpreted in the browser. This allowed us to get started right away without dealing with a development environment. I thought that my mission was easier than expected, but the hard part came later.

Chapter 2. The command line

This has been super easy too. My sister had a blast browsing through folders, creating files, and moving them. She is not a programmer, but she has a clear understanding of what an interface is. The command line is just a different way of doing actions that she already knows. Simple, great, let’s move on..

Chapter 3. The web

The first little difficulties begin. A non-technical person doesn’t know that a file can be opened with a browser. She knows that files behave differently depending on their extension, but the browser is a different thing. “It’s internet, it’s something else” she said. For her a file is a file, what she sees in the browser is just a page.

Lesson learned: the words I use don’t mean the same for everyone. It’s important to agree on the names of things. It takes time.

Chapter 4. Html

What’s a “tag”?, what’s a “markup”, are those tags “instructions”?

Lesson learned: the correct name of things is not always the most understandable. Everything needs an explanation. Everything.

“I want to write the title” she said, she clearly wanted to write a <h1> not a <title>, she doesn’t know what <title> does. And she doesn’t have to know it right away.

Chapter 7. Javascript

We have our own page, we have included our first javascript. What happens now?

Well, it’s useless to start with vague concepts. Variables, cycles, selectors, constants … these things make sense for two programmers, not for two sisters.

Better to start with something concrete, a small task. My sister wants to write a big red button that does “Booooom!” when clicked. Easy, isn’t it? anyone could understand it.

Lesson learned: always refer to something real, no abstract concepts.


This post is part of a series:


No copyright / do whatever the hell you want with these contents
Built with Hugo and Kiss theme. Hosted on Netlify. Icons made by Ddara