Let’s Teach Coders to Write

If we want to teach more people to code, we need more coders to explain what they do and how they do it.

I’m not going to re-hash the “teach everyone to code” arguments. I figure that’s been covered enough. For the record: I don’t necessarily believe everyone should learn to code although I DO believe that everyone should continue to learn and adapt to changes in technology if they want to remain relevant (and employed).

I would also say that it helps no one to create an artificial line between “us” and “them” that implies that you either know how to code or you don’t. It’s much more useful to talk about how to create pathways to allow people to progressively attain knowledge and, we hope, eventually attain mastery of new skills.

What I do believe is that technically-minded folks (myself included, although I’m not THAT technical) who are pushing others to learn technical skills could be doing a lot more to create (or at least make more apparent) these pathways and work harder to make the barriers lower for the people who earnestly do want to learn this stuff.

One of the simplest ways to do this is to write better documentation. That’s right, something we should all be doing anyway! (although I’m as guilty as the next guy for skimping on this). There will always be a place for books and step-by-step resources to learn a new programming language or to get up to speed with a more in-depth topic, but one of the best ways to improve incrementally (for me at least) is to look at an existing project and try to understand what it does and how it works.

The key is to write documentation not just for yourself or the other members of your team, but to write it with the assumption that your target audience is not as technical as you.

So, for example, if the installation instructions for your next app start (as many do) with something like “this assumes you already have these software packages installed” (plus the implied: and you’re comfortable with the command line, can clone a git repo and get a server up and running) then I would urge you to at least link to resources to help people get over that hump if not actually take the time to walk people through all of that.

The people who already know all of that stuff will just skip it but those who need a hand will be more likely to actually use what you’ve created because they won’t get frustrated and give up. And you can also feel good for having potentially helped people level up their skills.

Of course it would be great to carry this through to other elements of your project (including more comprehensive readme files, inline documentation, etc.) and even supplementing occasionally with a blog post explaining how you did what you did, why you made certain decisions, etc. but even doing some of this for every project would be a huge help to people who need a bit of a hand.

Again, always consider your audience! It’s probably not just other developers.