Explaining code non-coders

Thursday, December 16 at 10 AM (Edited Tuesday, April 4 at 7 PM)

We've all been there. Suppose you're talking to a friend about something that is really cool that you just made, what about if you're trying to explain a project that you need funding for to a potential investor? Maybe you're just trying to explain your convoluded code and thought process to a random stranger you met on the street. Who knowns. In this article I'll focus on 3 main strategies that I've found useful when explaining coding or projects that I've made to other people.

Method 1: Use an analogy

It's often incredibly useful to use an analogy to describe what you're working on as an analogy to something else. Here are some examples of famous people using analogies:

You see, wire telegraph is a very, very long cat. You pull his tail in New York, and his head is meowing in Los Angeles. Do you understand this? And radio operates the same way; you send signals here; they receive them there. The only difference is that there is no cat.

– Elisabeth Kubler-Ross

In Gmail, a label is a pointer to an email or a list of emails. Many labels can point to the same email. This is similar to assigning another variable to an existing variable:

let work = [email1, email2, email3];let important = work;

Both work and important are now labels that point to the exact same list of emails.

Method 2: Jump straight to the point (KISS)

Keep it simple stupid.

This is incredibly important. You can't ramble on about what streams are in Node.js while explaining your file upload system. Instead it's a lot better to just jump right into what you're talking about.

Here are a few things to focus on:

  • Why: Why is your project useful, nessecary, and why do you want to make it?
  • How: How will your project accomplish its end goal, and what steps does it need to take to get there. Try to keep the amount of steps to a minimum while explaining, ~3 steps should be easy enough to understand, but succint enough to convey your point
  • What: What do you need to complete this project? This should be the concluding statement, and it should describe what resource you might need. If talking to a potential investor this is very important. If just trying to explain to someone informally, simply mention what programming language you're using and any large frameworks you're using and what they do.

Method 3: Explain the end product using pictures and video

It's also important to describe the end product of what you're working on, and remember that a picture can say 1000 words. If you have a screen recording, demo, design sketch, or something like that, it's great to show that to the person. Pictures and media greatly help others understand your vision, and consequently your motivation, and the features that the project should/does have.

If you don't have any media that supports your project I highly suggest you make some. A promo video under 50 seconds is ideal, as well as some design screenshots from Figma, or a beta version that you're working on.

Here's a good example of a simple demo which explains a lot about a project: OnDrop file sharing gif

Concluding:

In conclusion, I hope all of this advice will help you sometime! If you enjoyed this article don't forget to follow me on GitHub!

Recent posts

Cryptography using JavaScript

JavaScript Web API Crypto API

How to guide for hashing, signing, encryption, debunking VPNs and more!

Creating an end to end encrypted authenticator and password manager

Auth Security Encryption Hashing

The process and data flow of implementing a super-secure 0 knowledge storage system, where all data is securely encrypted

Explaining code non-coders

Explaining Code How to

How to explain code and generate interest in your projects if the person you're explaining it to doesn't code

How I made working code examples in my blog

Code editors iframes interactive

How I created a working code editor that I can now embed in my blog to demonstrate and run code!