How to communicate with non-programmers

#todayilearned #career #beginners

TL;DR notes from two articles I read today.

Remember communication is complete when you are understood and not when you have said what you had to say. When communicating with people outside of the programming world, stay away from using technical jargon. It can make people feel excluded and it can confuse them.
It’s often necessary to simplify things. Be respectful, and never condescending, while doing that. Try explaining things in a step by step fashion, mention what edge cases are you considering with an example or two, and present a generalised gist.
Before an important meeting with non-technical stakeholders, work with a non-technical person as a sounding board to help you see if you’re making sense to your audience.
Try to personify or use analogies when explaining yourself. Use visual analogies - draw diagrams, tables, charts, flowcharts and the like to help illustrate your points.
When explaining performance metrics, find a middle ground between accuracy and understandability.

Full post here, 14 mins read

Begin with a backup - copy everything to a safe place in read-only mode. And check if the codebase has a build process and that it actually produces what runs in production.
Freeze the DB schema until you are done with the first level of improvements. It allows you to compare the effect your new business logic code has compared to the old business logic code.
When adding instrumentation to the old platform in a completely new database table, add a simple counter for every event and a single function to increment these counters based on the name of the event.
Never try improving both the maintainability of the code or the platform it runs on at the same time as adding new features or fixing bugs. It will invalidate some of the tests you made earlier.
When migrating to a new platform, all business logic and interdependencies should remain exactly the same as before.
Test the new DB with the new code and all the tests in place to ensure your migration goes off without a hitch.

Full post here, 11 mins read

DEV Community