Episode 125
| February 28, 2018
| 41 minutes
You must be an engineer
Have you ever found it difficult to explain how something works to a co-worker? What about reading documentation? We have all been there before and in this episode we chat with Ray Kim about his thoughts on how we can be better at communicating technically.
What is interesting is the number of tools that are now available to help us with communicating ideas; however, we all still struggle with communication.
Have you come across a situation like this?
Link to Grammarly.com article – https://www.grammarly.com/blog/effective-communication-skills/
When I started preparing for this episode, the following joke came to my mind:
A man is flying a hot air balloon and realizes he is lost. He reduces height and spots a man down below. He lowers the balloon further and shouts, “Excuse me. Can you help me? I promised my friend I would meet him half an hour ago, but I don’t know where I am.”
The man below says, “Yes, You are in a hot air balloon, hovering approximately 30 feet above this field. You are between 40 and 42 degrees N. Latitude, and between 58 and 60 degrees W. longitude”.
“You must be an engineer,” says the balloonist.
“I am,” replies the man. “How did you know?”
“Well,” says the balloonist, “everything you have told me is technically correct, but I have no idea what to make of your information, and the fact is I am still lost.”
The man below says, “You must be a manager.”
“I am,” replies the balloonist, “but how did you know?”
“Well,” says the man below, “you don’t know where you are, or where you are going, You have made a promise which you have no idea how to keep, and you expect me to solve your problem. The fact is you are in exactly the same position you were in before we met, but now it is somehow my fault.”
Episode Quotes
“How does somebody get better at technical communication?”
“The short answer is, practice.”
“Knowing [your target audience] definitely goes a long way in putting out a quality document.”
“There is such a thing as a document development life-cycle. Obviously, everybody’s heard of SDLC, the software life-cycle. The process between the two is identical.”
“There is such a thing as bad graphics. It’s entirely possible that a picture could be worth exactly zero words.”
Listen to Learn
00:51 Intro
01:37 Compañero Shout-Outs
02:46 Request for feedback on the new podcast format
03:36 Conference announcement
04:36 Tips & Tricks
06:05 Intro to the guest and topic
06:58 “You must be an engineer” story
11:44 Elements of good documentation — KISS Principle
14:02 Understand your audience
16:52 There is such a thing as a document development life-cycle – testing is vital
18:23 A picture is worth a thousand words
20:56 Is there a future in video being used for technical documentation?
22:41 Sometimes a written document is going to be the best
25:29 Grammarly article about what makes a great writer – a good sense of empathy
26:40 What stops people from doing better documentation?
28:48 Example of bad documentation
31:59 Points of good writing
35:02 SQL Family Questions
39:03 Close-Out
Credits
“Happy Rock” for Tips & Tricks by https://www.bensound.com
Music for SQL Server in the News by Mansardian
Our Guest
Ray Kim
Ray is an advocate for documentation and technical communication. He is active with SQL Server and UX user groups around Albany, NY, and has spoken at numerous SQL Saturday events around the northeastern United States. He has worked various positions in technology, including as a developer, webmaster, analyst, technical writer, and instructor. He holds an MS in technical communication from Rensselaer Polytechnic Institute and a BS in computer science from Syracuse University.
A musician in his spare time, Ray plays four different instruments. He also enjoys going to ballgames and doing CrossFit, and is a two-time SQLServerCentral.com fantasy football champion. He lives in Troy, NY with his wife, Lianne, and their two cats.
Meet the Hosts
Carlos Chacon
With more than 10 years of working with SQL Server, Carlos helps businesses ensure their SQL Server environments meet their users’ expectations. He can provide insights on performance, migrations, and disaster recovery. He is also active in the SQL Server community and regularly speaks at user group meetings and conferences. He helps support the free database monitoring tool found at databasehealth.com and provides training through SQL Trail events.
Eugene Meidinger
Eugene works as an independent BI consultant and Pluralsight author, specializing in Power BI and the Azure Data Platform. He has been working with data for over 8 years and speaks regularly at user groups and conferences. He also helps run the GroupBy online conference.
Kevin Feasel
Kevin is a Microsoft Data Platform MVP and proprietor of Catallaxy Services, LLC, where he specializes in T-SQL development, machine learning, and pulling rabbits out of hats on demand. He is the lead contributor to Curated SQL, president of the Triangle Area SQL Server Users Group, and author of the books PolyBase Revealed (Apress, 2020) and Finding Ghosts in Your Data: Anomaly Detection Techniques with Examples in Python (Apress, 2022). A resident of Durham, North Carolina, he can be found cycling the trails along the triangle whenever the weather's nice enough.
Want to Submit Some Feedback?
Did we miss something or not quite get it right? Want to be a guest or suggest a guest/topic for the podcast?