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

About 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.

Ray’s blog: https://pianorayk.wordpress.com/

Credits

“Happy Rock” for Tips & Tricks by https://www.bensound.com
Music for SQL Server in the News by Mansardian

**Sound effects have been removed from the recording**
*Untranscribed introduction*

Carlos:                 Compañeros! Welcome to Episode 125 of the SQL Data Partners podcast. It’s good to have you on the SQL Trail today. Our topic for today is You Must Be An Engineer. Ultimately, we’re talking about technical writing and how to communicate technical terms to your coworkers or those who are going to come after you, management, whoever the audience might be, there. Our guest today is Ray Kim. Ray is coming from the northeastern United States and has been talking quite a bit about technical communication and so we’re excited to have him on the program, get some of his thoughts. So, we’re interested to get some of his takes on how we might improve some of the documentation that we’re putting out, if we’re putting any documentation at all.

So we do have a couple of compañero shout-outs today. One, we wanted to give a shout-out to Mohammed Owais and Thomas Kronawitter. These are both a little delayed, so we apologize, guys, for this delay, but they were checking in with us.  They had noticed that we had missed a couple weeks. Just wanted to check in, make sure everything was okay and that at least a couple compañeros were paying attention.  We also saw Lucas Fernandez of Argentina showing off on social media his SQL Trail T-shirt. You’re looking good, Lucas! I want to give a shout-out to Rick Heiges. He’s from Dbbest. They do quite a few Oracle migrations, Oracle to SQL. I had some questions, and I thought it was interesting that I could reach out to him and get some insights from a competitor, basically on what I might be able to do as I service some of my clients. Also want to give a shout-out to Douglas Kemp. Douglas Kemp actually was the one who approached us about doing the Tips & Tricks, originally. He also wants us to talk about the on-ramp to Azure SQL Data, how people have been making that migration and some ideas on what he might need to know to get started there. So we do have some ideas for that, and in another episode we’ll be talking about that.

Now, compañeros, you’ll notice the last couple of episodes, we have included some additional sounds and I’ve gotten a little bit of feedback and I want to get more feedback. So, we are trying to do some different things. At the end of the day, I want to have a little fun with this, and my thought was to include some sound effects, for lack of a better word, into the program. That’s not necessarily coming across as super helpful for some of you, and so I’m interested to know, what do you think? Is it adding value, is it detracting, is it a plus, or is it a negative? Be honest, ultimately, I’m very interested in interacting with you. I don’t want to add more work to myself here, but if it makes it a little more fun, a little more interesting to listen to, then that’s what it’s all about for me and I’d be interested in getting that feedback.

So, I do have a little bit of information on the Compañero Conference. The dates aren’t yet finalized, but I can say that it is coming. One of the goals that I had for myself, if you listened to the Retrospective, that I wanted to have at least one sponsor before I moved forward with the conference again. I have that sponsor now, and so while all the details aren’t yet available, we do know the following: One, it will be held in Richmond, Virginia. We know we are going to go to two and a half days as opposed to the two days we had last year. So, we’re going to start on the afternoon of what we think is going to be a Wednesday, so Wednesday to Friday. And then we also know that on Friday we are going to have labs. So those are the some of the details that we’re still working out, but as far as the when and the other details, that will be coming in future episodes. So if you have plans for training or you don’t know what you’re going to be doing, we’d of course love to have you on the SQL Trail.

So now, time for a little Tips & Tricks on the SQL Data Partners Podcast. This one is a new feature I saw with Management Studio. So, the scenario will be that you have run a runtime query. These are normally queries that haven’t gone into Reporting Services or things like that, but for whatever reason, there is some data that you want to put into Excel that you’ve got to send to somebody. It’s not going to be repeated, but they need this query and they want you to give it to them. It used to be that you had to go run the query, copy it out and then stick it into an Excel and then save it as the .csv and whatnot. It used to be a little cumbersome. Well, you’ll notice now that here I’m running my query, SELECT * FROM CAT and I want to take the output of this and I want it to send it in a .csv. So what I can actually do is right click on the data here, Save Results As and now the option is I can actually save that result set with the header as a .csv or a tab-delimited file and I can skip that, as far as the copying and pasting it. So I thought that was kind of a neat little addition, an enhancement to SQL Server Management Studio. The music for this segment is called Happy Rock from bensound.com used under Creative Commons. So that is your Tip & Trick for the week.

The show notes for today’s episode are going to be sqldatapartners.com/communication or sqldatapartners.com/125. Okay, so let’s go ahead and get into the conversation with Ray.

 

Carlos:             So Ray, welcome to the program.

Ray:                 Thank you, great to be here.

Steve:              Yeah, it’s great to have you on the show.

Carlos:             Yes, so from upstate New York. We don’t get too many from up that way and while we haven’t quite hit spring in the United States, we’re glad to know that you haven’t frozen this winter.

Ray:                 It was a lot worse a few weeks ago.

Carlos:             Oh, I bet, oh man, yeah it seems like lots of snow up in your area in the wintertime.

Ray:                 Right, and anytime you see a temperature that has a minus sign in front of it, that tends to, shall we say, make you hesitate?

Carlos:             Ultimately, our topic is about technical communication and so I want to start this dialogue off with a story, which you may have heard before. The story goes that this man is flying around in a hot air balloon and he realizes he’s lost. He sees somebody down below, so he goes down a little further and he shouts to the man on the street there walking, and he’s like, “hey, I promised somebody I’d meet him. I’m trying to get there in this air balloon, but I’m about an hour late and I don’t know where I am.” So, the guy down on the ground says, “well, you’re in a hot air balloon, you’re hovering about 35 feet in the air and you’re at such-and-such latitude and longitude.” The guy in the balloon says, “you must be an engineer.” The guy on the ground says, “I am, how did you know that?” And the balloonist says “well, everything you told me is technically accurate, but I have no idea what to make of your information and the fact is that I’m still lost.” And the guy on the ground says “well, you must be a manager.” And the guy in the balloon says “I am. How did you know that?” “Well”, says the man on the ground, “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 that you are in the exact same position as you were before we met, but now, it is somehow my problem.

Ray:                 I like that. I’m going to have to remember that.

Carlos:             So, I think this kind of sets up this conundrum that we have between the IT worker and the non-IT worker. And everybody has experienced it, and we have experienced it lots of different ways. It could be outside of technology as well, whether that’s with a spouse or a partner, or whatever else and one person is saying something but the other person doesn’t quite get it or understand it.

Ray:                 Right, yeah, you’ve pretty much hit the nail on the head. As a matter of fact, one of the things I was going to mention, that technical communication may not necessarily be about technology, and you can’t see me over the air, but I’m using the air quotes around the word technology here.

Carlos:             Yeah, that can be very, very difficult and some of the projects and whatnot that we work on, even documentation. So documentation is one of those things that I think most of us, for lack of a better word, just dread, and don’t do so well, and we do it one, only if it were required, or two, we’re moving on to a new position and we kind of have to do a brain-dump of everything that we know for the next poor soul who has to take our spot.

Steve:              However, that being said, we’re also the ones who want the documentation when it’s coming from someone else.

Carlos:             Yeah, that’s a great point. So, we want to consume it, we just don’t want to create it.

Ray:                 Yeah, there’s a lot of that around, and one of the big reasons why I started doing these for my SQL Saturday topics was to make some kind of attempt, if you will, to fix that, I guess, address that. It’s one of the big, how shall I put this, elephants in the room, I guess. Everybody acknowledges that it’s important, we’ve got to do it, but nobody wants to do it.

Carlos:             How does somebody get better at technical communication?

Ray:                 The short answer is, practice. Just like everything else, I mean you want to get good at something, you’ve got to practice it.

Carlos:             Let’s take the vantage that that Steve brought up and let’s think about, so we all like to consume documentation and maybe even a step further is a lot of times, have you ever read a document and been completely unsatisfied?

Ray:                 Let me put it this way, welcome to my world. A lot of the times, a lot of the documentation I write, I write for exactly that reason. I’ll look at a document, I’ll say to myself, “this is a load of you-know-what, I can’t repeat that over the air.” And I’ll take that thing, I’ll start reworking it. Let me put it to you another way for any developers that are out there. How many times have you looked at a piece of code and said to yourself, “what the heck was this guy thinking?”

Steve:              It’s been a couple hours since I’ve done that.

Ray:                 And by the way, more often than not, speaking of someone how has done development work myself, more often than not, the code that I’ve seen is my own.

Carlos:             Yeah, the double-whammy, there.

Ray:                 Right, so a lot of the times I’ll look at that and I’ll say to myself, “what was I thinking?” So, no matter how good you think you are or how well you think you do something, there’s always room for improvement.

Carlos:             What then makes a good technical, I guess, for all intents and purposes, we’re talking about, we can talk about verbal communication, but I think maybe for a minute we’re talking about the written communication, so documentation. What are some of the elements of good documentation?

Ray:                 Well, I think one of the big things is, you’re familiar with what’s called the KISS Principle, yes?

Carlos:             I am.

Steve:              Keep It Simple.

Ray:                 Yes, correct. I think that’s one of the biggest things that we need to do in terms of writing good documentation. And there are too many people who don’t understand that. I’ve seen too many cases where a person is trying to write some kind of technical document, let’s say, a step-by-step instruction, just to throw an idea out, and this person insists on including every little step and every single detail in there. That’s problematic for a bunch of reasons. Number one, it makes it hard to read. One of the things that I espouse in my SQL Saturday presentations is that reading is work and people don’t realize that. When you’re going through a technical document, you don’t want to read a book. This is not a novel. I mean, how many times have you looked at a document or even just some writing or whatever, or even something as simple as say, an instant message from somebody, and all you see is this big black glob of text? Yeah, let me ask you something, do you really want to read that?

Carlos:             It’s tough, right, because I feel like I’m of two sides because I think back to my calculus days and there’s this cartoon where the calculus problem is on the chalkboard, and then the guy has the answer at the bottom and then in the middle he has “magic happens”.

Ray:                 Yeah, I’ve seen that one.

Carlos:             And then you just have the answer. And so I guess I can agree, and it makes a lot of sense that the detail is a killer. I think that’s a great point, but I guess I’ve also been in that place where I feel like, okay, well, you’ve started with the problem and you kind of have this answer here, but I have no idea what’s in the middle.

Steve:              And I think a key part of that, and I’d be curious your thoughts on this, but it’s really understanding who the audience is.

Ray:                 That is a huge part of it, yes.

Steve:              There are some people that you have to use that amount of detail to be able to get the point across and to get it clear, and there’s others where maybe you’re more on the same wavelength and you’re able to just keep it short and they get the point, like the calculus proof. I think it if it was someone who doesn’t know calculus as well, they probably need a lot more details.

Ray:                 Knowing the answer to that goes a long way in determining what kind of document you’re going to write, how it’s going to be written, what kind of formatting you’ve got to use, what level of detail you’re going to use, what buzzwords you’re going to use and so on and so on and so on.

Carlos:             Do you actually include that in your document? Do you actually say ‘this is intended for you, X person’?

Ray:                 As a matter of fact, yes, I do. One of the things that I try to do is I’ll include a section that says Assumptions and I’ll say something to the effect of ‘this document assumes you understand T-SQL’.

Carlos:             Or X, Y and Z.

Ray:                 So, there are a lot of times when you write this stuff and you have to make some assumptions as to who is going to be reading this thing. Unfortunately, there’s not much of a way around that.

Steve:              I was just thinking of an example just today that happened where I was looking at some quote, technical documentation on a process, that was part of a database system that was doing finance data for a company and it became very clear that the audience it was intended for was the controller at the company and not the technical people. And as I dove through it, I realized there was very little value that would help me, looking at stored procedures and webcode, to figure out what was going on. It was all intended for the end user who was going to be, who was an accounting, a finance person, you know? And I think that that’s one where the assumption was, that’s it, that’s all the technical documentation there was. But it was technical from the wrong perspective, I think.

Ray:                 Yeah, you’re exactly right. I come across that all the time. There are documents out there where it explains some really good concepts, but you suddenly realize halfway through it that you’re the wrong audience. You are not the person who this is targeting and that can be frustrating when you’re going through instructions.

Steve:              Yep, and what’s interesting is when you’re the one writing that documentation and you need to get buy-off from different areas. You need to get buy-off from some technical people as well as from maybe some management or marketing people that are outside of the technical realm.

Ray:                 That is correct.

Steve:              And the same document may be expected to work for both of those environments. And I think what ends up happening with that is it ends up being worthless to both parties, probably.

Ray:                 One of the things in my career is I have been blessed with the fact that I have actually worked in both a software development environment and I have also worked in a professional technical writing environment. And one of the things that a lot of people don’t realize is that there is such a thing as a document development life-cycle. Obviously, everybody’s heard of SDLC, the software life-cycle and the process between the two is identical. There is no difference. I mean, when you’re creating a document, you have your planning stage, your development stage, your testing stage, yes, there is such a thing as testing a document.

Carlos:             Hey, read this, do you understand it?

Ray:                 Exactly. The first thing I do, is any time I write a document, I’ll send it off to people. I never, ever send it out into production right away. I’ll have people review it. I’ll say, “guys, take a look at this. Is what I wrote accurate and can you follow it?” I’ve even taken draft documents and I’ve put it in front of people and told them “go through this thing and follow the instructions and let me know if they work for you.” So, once you get that feedback, you get your results back, you take it back, you’re going to have to do a little bit of tweaking, and then you go back through the process again, rinse and repeat.

Steve:              So, what are your thoughts on pictures or diagrams in the documentation? Because know sometimes it seems like they’re helpful but other times it seems like they’re done poorly and they’re more damaging than not having them?

Ray:                 A picture is worth a thousand words. You’ve heard that saying all the time, it’s an overused cliché, but it’s true. I remember very early in my career when I started doing documentation, I did some support and operations work way back when and one of the devices that we had was a WORM Jukebox. I don’t know how many listeners are going to remember those.

Carlos:             I was going to say, I remember jukebox, but WORM Jukebox?

Ray:                 Yeah, WORM, it’s an acronym for write once, read many. Optical platters is what it was.

Carlos:             Ah, okay, there you go.

Ray:                 And basically, the jukebox was located in an area that was traversed by a lot of operators doing other things. And of course, you know, just like any other technical, or any other mechanical device, it’s going to break down. So, we couldn’t be there 24/7 to keep this thing operational, so we came up with the idea of teaching these people how to operate this device. Now, platters were kept in a cabinet and they had to be inserted into the jukebox a certain way. So, the first problem that I came across was how do I explain to these people that the A side has to be up, this side has to be facing towards you, it’s got to be inserted this way, and I tried writing that out and was having a lot of trouble doing so. Now, that’s when I came up with the idea of drawing a very rudimentary black and white, I don’t want to say stick figure, but a simple drawing in. I will say this, it’s long enough ago that I don’t remember the details. I mean, we’re talking Windows 95 software, that’s how far back it goes.

Carlos:             Yeah, so Paint or something like it.

Ray:                 Right, whatever it was. And I sketched out what it should look like, and I put it in this document and next thing I knew, I had an instant working document that worked well for these operations people. And it actually became a very successful document.

Carlos:             Yeah, that’s interesting that you bring that up, because we talked about different audiences, but then I also feel like there are also different mechanisms now, or different ways to record that document. We’ve been talking a little bit about written word, but how many times have you gone to YouTube to look something up?

Ray:                 Oh, all the time.

Carlos:             All the time, right? It seems like at least in video form, for the most part, those seem to be very structured, and it tends to be, I won’t say corporate, so it’s some kind of training, like harassment or some corporate policy training that would incorporate some video, but I wonder if video or audio might increase, or might make our lives a little bit easier if we start thinking about some of this stuff. I don’t see it very much. Are you seeing that adopted at all?

Ray:                 I can’t really say, because in the environment that I’m in, I probably haven’t been exposed to a lot of that.

Carlos:             Well, I mean, I don’t see it. Do you see it, Steve?

Steve:              Well, I don’t see it in-house at a lot of places. I see a lot of things where people are doing that on YouTube, everything from how to fix your plumbing to how to do SQL queries. And I think there’s a real mix there of what’s done well and what’s done poorly, but I just have a feeling that if you’re working in an office environment and suddenly you start loading up the network location where all the documentation goes with a bunch of videos, that suddenly someone’s going to start complaining about the amount of disc space you’re taking up, when it could be done in a Word document that was much smaller. Whether or not that’s a better way or not, that’s a whole different argument.

Ray:                 My personal opinion to that is, it depends. It depends on, once again, let’s go back to, it depends on who your target audience is. Are they going to want to see a video of this and would it be helpful for them to see a video? But at the same time, I’ve also come across instances where a written document is probably more appropriate. I’ll tell you about something I’ve come across relatively recently. One of my projects lately has been working on an internal social network, if you will. This actually kind of goes back to our discussion about graphics and layout and design, but let me back up a little bit here. I will say that I have a love/hate relationship with this network that they put together. I like the concept, which was basically trying to keep the entire company informed, which is a noble concept, it’s understandable.

Carlos:             Right, that’s what everybody wants to say. So, we’re not doing social media here, we can’t just keep tweeting or updates, but so okay, what’s kind of the middle ground here?

Ray:                 I wasn’t crazy about the execution. I’ll tell you what, one of my biggest frustrations about this site that they put together is a very simple question that should be answered only by the UX, this is not something that you should have to go to a document to read the instructions for and that question is, where do I begin? I’m here, I’m sitting here looking at this intranet site trying to figure out where am I supposed to go in this interface and I couldn’t answer that question. Now, going back to our discussion about YouTube videos, they included this section of videos for getting started, and I was going through this thing and I was saying to myself, “I don’t want to listen to videos to go through this thing, I either want to read a document to figure this out, but even before that, I shouldn’t have to read a document to figure out the answer to my question.” A good interface, and going back to our earlier thought about graphics, is that a good interface should answer that for you without having to look it up.

Carlos:             Sure. So, if we were to apply that to us, cause we do have some developers listening, and I’m not sure how many of them are necessarily UX folks, but I think the application there would be self-documenting code or practices that are going to say, “here’s the structure, here is how things are set up” and if you wanted to take a peek, everything is kind of set up in a similar fashion, rather than give them a hodge-podge of different things.

Ray:                 I think one thing that would help that out, this comes out of a webpage I came across recently. Grammarly.com, I came across an article that talked about a number of things that make a great writer. What I’ll do is I’ll send you the link to this thing so you can post it along with the webcast, but I remember one of the things I saw on there was having a good sense of empathy. What is the reader or your target audience feeling? Going back to that instructional document about the WORM device, one of the things I said to myself when I sat down and wrote this thing was, “okay, I’m sitting in the operator’s shoes, if I was reading this document, what would I want to see?” and one thing I discovered was that that mindset actually went a long way in trying to figure out how to write this thing and where to go with this document. So I’ll send you the link. It’s all in there. It’s a really good read.

Carlos:             Admittedly, I was hoping a little bit that there would be this “oh, here, you just follow these three steps and this will solve all your problems.”

Ray:                 If only it was that simple.

Carlos:             I think at the end of the day, what we’re getting at is, just like everything else where it takes thought and planning, and you do have to get out of your own shoes a little bit. I think self-questioning, “hey, if I wanted to read this document, what would be helpful to me?” Yeah, I think a great question, but super hard as well, because the reality is I think, so my immediate thought is the scope creep. Well, maybe not scope creep, but just the sheer amount of information that we’d want, you’re like “ah, too hard. Let’s not even start.”

Ray:                 That’s true. That may be one of the things that probably discourages a lot of people from doing better documentation. I mean, I’ve worked in different environments and I’ve heard excuses like, “this takes too long. I’m not a good writer. I’m terrible at this.” One of the really big ones, and this just really ticks me off, is there are too many people out there who are saying it just isn’t a priority. I mean, more often than not, you look at environments out there and let’s say they’re cutting staff and budgets and writers are often one of the first people to get cut.

Carlos:             Yeah, if you even have a writer. I don’t know that I’ve ever worked in an organization that’s had a technical writer. I mean, there’s been marketing people, but there’s never been anybody assigned to the IT group to do any of that writing.

Steve:              I think what it comes down to in that is that the technical people are the ones who end up doing the writing. And back to the arguments that you were calling out there, the things like I’m not a good writer, or I don’t have time for it or it’s not a priority, those kind of things, that all comes down to the environment you’re in and the trust and understanding. If you’ve got someone who’s a great developer but they’re a horrible technical writer, they could probably still do great technical documentation for other developers to use but they may not be the people you want to have writing the technical documentation for the customers.

Ray:                 As a matter of fact, that actually brings up another great point. Let me back up a little bit, one of my previous jobs, they put together an admin guide, and I put that in quotes, by the way. Basically, what they did was this guy took all of his scratch notes, completely unorganized, nobody could follow this documentation to save your life. This guy insisted on putting the same information in multiple places, which in itself brings up a problem of maintaining this thing, but I won’t talk about that now, just for the sake of time. But basically, he threw this thing together and put it in a Word doc and sent it to the customer and said, “here’s your admin guide.” And this thing was full of grammatical mistakes, it was nearly impossible to follow, there was absolutely no organization whatsoever. I remember going through this thing. I couldn’t read it.

Carlos:             So what should be a good flow? We talked about testing it, meaning giving it to somebody else to read. But what’s a reasonable expectation, if we’re going to take the time, now again, I’m a technologist and I’m writing documentation, what’s a reasonable expectation to have that proof-read or have it reviewed?

Ray:                 That’s a tough question. The short answer is it depends. The longer answer is, it depends on what you’re documenting. It depends on the scope. It depends on the audience. It depends on a lot of things, so that’s not an easy question to answer.

Carlos:             Sure, I get that. Obviously, there are exceptions, but I would hope that most, and I guess if you’re a developer, maybe that’s a different scenario. But I’m hoping that most of us are not writing documentation that is going to be customer-facing.

Ray:                 As a matter of fact, one of my arguments for making sure that you have a good writer. Let’s say you are a customer and you receive, instructions, an admin guide, even just simple marketing materials and it looks like it was just thrown together. My question is, would you want to do business with this organization based on that document?

Carlos:             Well, unfortunately they’ve already paid at that point, so it’s a little too late to make that decision.

Ray:                 Well, yeah.

Carlos:             Doesn’t give you the warm fuzzies, I’m sure.

Ray:                 No, it doesn’t and basically if you get a poorly written document from your company, like you said, it doesn’t give you the warm fuzzies. And the question, would you want to do business with them again?

Steve:              And I guess it really comes down on that documentation to, were they able to convey the point to the point you could use it even if it was poorly written? I mean it would certainly impact whether you were going to do business with them again.

Carlos:             If were to make a checklist of things. So, if I wanted to get better at writing, number one on my list, practice. Number two, think about the audience. Who is this intended for? Then depending on who that audience is, it’s going to specify the level of detail that I have. Maybe I think about different forms of documentation, so images, words, we talked a little bit about audio or video as well, depending on the situation. And then trying to keep that as simple as possible.

Ray:                 Sure, there are a lot of other points, too. Probably too many to include in just one single podcast, so I won’t go through all of them. I will mention a couple of more things. Going back to the illustrations/pictures thing of a picture may be worth a thousand words, however, if you don’t use them properly or don’t use them well, there is such a thing as bad graphics. It’s entirely possible that a picture could be worth exactly zero words.

Carlos:             Sure, does that really come down to just like the resolution or the size or what are some of the factors there?

Ray:                 No, this is nothing to with size or resolution. What is the context that you’re using the image? Let me give you an example from my last job. These people absolutely insisted on putting out a checklist that was done on Microsoft Word first of all there was absolutely no way in heck that I would have put it in Microsoft Word. First of all. But they put this thing out with absolutely no testing, no feedback whatsoever. And these graphics that they had that were supposed to be quote/unquote helpful, now you know how Microsoft Excel works, you have multiple tabs on there. What this person did was, he put this graphic on a separate tab and on this checklist, you had a hyperlink that went to that tab. Now first of all, right off the bat there, you’ve got the problem of having to go back and forth between the tabs, which is a pain. I mean, if you’re a reader, do you want to do that?

Carlos:             No, I don’t want to do that.

Ray:                 Right, and number two, you looked at the graphic itself and the graphic was useless. It was long enough ago that I don’t remember what the graphic exactly was, but I’ll give you this analogy. Have you ever looked up something on Google Maps and the point of Google Maps is zoomed in so close that you don’t see the name of the street, you don’t see the name of the business, you don’t see what city or even what state it’s in? What good does that do you? So that’s what I’m talking about. I mean, your graphics are just as important as what you write. So that’s an example that I would give you of a graphic that is worth exactly zero words. It’s useless. I mean, what’s the point of having it?

Steve:              Okay, so then, with that shall we wrap it up with the SQL Family questions?

Ray:                 Sure.

Steve:              How did you first get started with SQL Server?

Ray:                 That’s a good question. I’ll be honest with you, that’s pushing my memory because it goes way back. I will mention that my first experience with databases was my first job out of college. I was a lowly computer operator making sure things were backed up and things were functioning, and I had to check on tapes for a database. This is going way back, called Informix. I think Informix is still around. I’m not sure.

Carlos:             I think they are.

Ray:                 I remember learning a little bit of T-SQL there, and that’s pretty much where I first started. A later job, I actually worked on a project where I came up with an automated server inventory system.

Ray:                 I actually managed to come up with a system that pulled all of that information off of there. That was pretty much my first big foray into SQL Server.

Carlos:             Now, with that time in SQL Server, if there’s one thing you could change about the database, what would it be?

Ray:                 Well, first of all, let me say that right now I am working in an Oracle environment. Don’t judge me. I am biased towards SQL Server, I would really much prefer working with SQL. I’ll often joke with my friends like, “oh, I hate Oracle, blah, blah, blah.” One thing that I do like about Oracle that SQL Server does not really do is basically opening and committing transactions. The reason why I like that is it prevents mistakes.

Carlos:             I guess I’m not quite sure that I follow what you’re saying because it is transaction system.

Ray:                 Yeah, what I mean is SQL Server includes the clause to BEGIN TRANS/COMMIT TRANS. SQL Server basically, it’s not intertwined, if you will. The BEGIN TRANS/COMMIT TRANS don’t actually happen unless you specify it to happen. Whereas in Oracle, it pretty much makes you do it. Once you run a transaction in Oracle, you pretty much have to commit it. It makes you do it. The reason why I like that is that it prevents too many, if you will, oops moments in SQL Server. How many times have you written some DELETE FROM TABLE and you realize, oops, I didn’t want to do that? So, there’s a reason why I got in the habit of writing the WHERE clause first before writing the actual SELECT or DELETE statement.

Steve:              Okay. So, what’s the best piece of career advice that you’ve received?

Ray:                 I don’t remember a piece of advice that I myself received.

Ray:                 One of the big reasons why I’ve been focusing more on writing communication is I’ve noticed that as I get older, my interests and my career choices tend to change a little bit. Years ago, I really wanted to be a developer, a programmer, whatever, and as I got older, what I’m finding out is I enjoy doing development work, but I’m not as passionate about it as I was once upon a time. Whereas, now I’m finding out that I’m much more passionate about communication and writing. So, having said that, I would say if had to at least give a piece of advice, I would say, probably go with your strengths.

Carlos:             So, our last question for you today, Ray. If you could have one superhero power, what would it be and why do you want it?

Ray:                 Considering the line of work I’m in, I’d say reading minds.

Steve:              Rather than needing documentation?

Carlos:             Yes, especially of dearly departed co-workers, right? You’d be like, “huh, I’d love to be able to grab some of that information.”

Ray:                 Yep.

Carlos:             Awesome. Ray, thanks so much for joining us today. We do appreciate it. Great insights.

Ray:                 Thank you for having me. It was a pleasure.

Carlos:             Yes.

Steve:              Thanks, Ray.

Carlos:             So compañeros, we hope you found that interesting. I do think, as always, getting other folk’s take on what they do and how we can be better. We will point you to the Grammarly.com article that he mentioned. Ray didn’t seem to necessarily agree with me here, but I do believe that there are going to be additional ways other than just typing in Word, that we’re going to be able to communicate some of these ideas. Obviously, I’m a little partial to the audio format. That may be a little weird in a corporate setting, again I think it’s just more about culture, but at the same time, and maybe to extend that just a little further, with video as well. So, if somebody had to choose between not having anything and seeing a video where you’re at your desk just talking into a microphone and trying to go through some of the motions to at least explain some of these things, I think they’re going to choose that latter. And so it’ll be interesting to see how that continues to evolve. Just think about the way that we get training. Yes, obviously there’s in-person events and SQL Saturdays and things like that, but you think about the amount of online training and things that we get and how we can begin to put that together. But I think there are some important concepts. So there are some additional things to think about, and that is practice does, in fact, make perfect. This is going to be something that you have to attempt multiple times. We talked a little bit about getting feedback. And as always compañeros, we’re interested in getting your feedback. You can leave us comments on the show notes page for today’s episode, which will be at sqldatapartners.com/communication, or you can reach out to us on social media. Our music for SQL Server in the News is by Mansardian used under Creative Commons. You can connect with me on LinkedIn. I’m @carloslchacon. And compañeros, I’ll see you on the SQL Trail.