Ask HN: How do you explain code verbally? | Hacker News Reader

Ask HN: How do you explain code verbally?

1 pointkypro4 comments

I've been asked to explain code via screenshare of some projects I've been involved with.

I find communicating code projects verbally weird. Any code of reasonable complexity in my opinion is much better communicated via detailed and well structured text documentation.

But compounding my issues is the fact I'm autistic and think about everything visually - this includes code which seems to take visual forms in my head. I don't know how to explain it, but I don't think with language and when communicating generally I feel as if I have to run my thoughts through a clunky mental transpiler.

I'd really like to be able to host great screenshare sessions where I can go through projects and explain things in a way which is clear and concise, but it seems no matter how hard I try, I can't do it.

I think I could do better if I had a lot of time to prep. This way I could create documentation with a mixture of text and imagery and go through that instead. But this isn't always possible.

I know some of you out there are verbally gifted, and I envy you, but for those of you who are not, have you been able to improve your ability to verbally communicate complex systems? Specifically, I'd appreciate hearing any strategies or processes you implement which improve your ability to communicate.

I'm also autistic, and had similar issues early in my career which turned out to be "too much information".

When explaining code, you need to paint with broad strokes. There are all sorts of nuances that would normally require extensive and careful explanations, but what you really want to do is a kind of ELI5 approach, then go into more detail if people ask for it (they almost never do).

It also helps to just keep practicing, getting feedback afterwards (people don't usually want to give feedback, but I've had success prefacing it with "I'm trying to improve my explanations, so solid feedback on anything that was confusing will really help!").

Screenshare would imply you can use slides. Craft a slide deck

- it will help you stay focused, plan a good sequence of points for your audience, a tour. What are they supposed to learn or know after this?

- architecture &| organization (with a diagram)

- highlight important areas of the code

- show flow from entrypoint(s) to important areas

- do not go line by line, do not go into the weeds

- do know your audience and craft it for what they are trying / need to learn from it. You are not trying to make them contributors most likely

- talk about the whys, not the hows

- don't fill the slides with text or code, put more text into the speaker notes if necessary (but avoid as much as possible) use links to code rather than code screenshots in the slides (exceptions)

If you want to get better, do it as much as possible. Practice makes perfect as they say, though it is never perfect in reality.

Thank you.

I love the bullet point list. I'll keep this bookmarked for next time. =)

I teach programming and have experimented with Codetry Readings(C)(TM);) (think beat poet) I have not hit the sweet spot of reading the code in idiomatic spoken language to match to idiomatic code language. Work in progress.

But now with added AI. I guess we could do better with better Chatbot-FU.

GPT-Chat code and description

Request: python program that takes two numbers on the command line and counts backwards from the first in steps of the second while the value is positive.

Oops did not know it would not preserve format Moved to google docs

https://docs.google.com/document/d/1aKeY1xYalymWIWY7pjoP7Nxw...

Request describe this code to a non programmer

This code is a program written in the Python language. It takes two numbers as input from the command line and counts backwards from the first number in steps of the second number, until the value reaches zero.

The program first checks if the two required numbers are provided as inputs from the command line. If either of the numbers is missing or cannot be converted to an integer, the program outputs an error message and terminates.

If the inputs are valid, the program sets the first number as the starting point, and begins counting backwards by the second number. It outputs each number as it counts, and stops counting when the value reaches zero.

For example, if the first number is 17 and the second number is 3, the program would output the numbers 17 14 11 8 5 2 in that order.

Reply on news.ycombinator.com