Month: October 2021

Upcoming speaking engagements (as of 10/26/2021) #ProfessionalDevelopment #PASSDataCommunitySummit #PASSSummit @SWEtalk #WELocal #Networking #SQLFamily

Since my last speaker’s update, two of my conferences are in the books, one is upcoming in just a couple of weeks (!!!), and a couple of potential new conferences may be upcoming for me.

First, I’ll talk about the two conferences I did.

  • Data Saturday #13, Minnesota: I spoke for this group last year, and it went very well! As virtual conferences go, the Minnesota SQL group does a great job of putting their event together! This year’s conference was no different! A number of tools that they had used last year were also in effect this year (I was happy to see that the Discord account I created primarily for this event still worked!), and it made for a great online conference! Only my personal schedule (I had football tickets for the night before) really kept me from taking full advantage of all this event had to offer. That said, as virtual conferences go, I recommend this one highly!
  • Rocket Mortgage TechCon 2021: When I tried to advertise this event, I found that I had trouble finding a link to allow people to register for it. As it turned out, it was for a good reason: it was a private internal event for Rocket Mortgage employees. Oops! In any case, I delivered my presentation and discovered a very receptive audience! I got a lot of good questions and plenty of interaction (which was somewhat difficult, because people couldn’t message me directly; the only way I was able to read people’s comments was to turn off my slide sharing). And as a result of my presentation, I now have several LinkedIn connections to Rocket Mortgage employees.

With that, here are the upcoming conferences where I’m speaking or have applied.

Confirmed

In two weeks, I will be speaking at PASS Data Community Summit! This is the third consecutive year that I am speaking at PASS Summit or its equivalent! Just being selected to speak at one is an honor, but being selected to speak at three straight is nothing short of amazing!

This year’s Summit is virtual and free to attend (although there is a fee to attend pre-con sessions). All you need to do is to go to the PASS Data Community Summit website and register!

I will be doing my session on joblessness and unemployment titled: “I lost my job! Now what?!?” I will share advice on how to survive a jobless situation, including (but not limited to) dealing with the stress and emotions of unemployment, how to shore up your job search and interview skills, and things you can do to pass the time.

I am scheduled to speak on Thursday, November 11, at 9:30 am Eastern time. Hope to see you then!

Submitted, but not confirmed

I’ve submitted presentations to two events, each of which would be a new one for me if I’m accepted to speak! Please note that I have only submitted to them, but I don’t yet know whether I’m speaking at them or not.

These events are NOT virtual; they are in-person! If I am accepted to any of these events, they would be my first live in-person events since SQL Saturday in Rochester last year!

In addition to these two events, there’s also my local user group:

  • CASSUG user group, Albany, NY: This is my local SQL user group. It’s been a while since I spoke for my hometown user group, and I think I’m due. I’m hoping to get to speak at one of our meetings!

So as of today, this is my upcoming presentation schedule. Hope to see you at an event sometime soon!

Advertisement

User testing is important — for documentation

Any application developer will (and should) tell you how important end user testing is for their product development. It’s an important part of the development lifecycle. Developers need to know if their applications actually work, if they work the way they’re intended, and if their interfaces can actually be used. Without user testing, developers put blind faith in what they produce, and they have to assume that their applications are perfect every time, all the time — which, as we all know, always happens. User testing is critical in ensuring that you create a quality product.

So how often does your documentation go through user testing?

I’ve said many times that document development needs to go through the same steps as application development, and this is one of those steps. It is (sadly) common for documentation to be released without being checked for accuracy or usability. This is another way in which document development gets absolutely no respect, whatsoever.

If you’ve written, say, a set of instructions, one of the best things you can do is to give it to someone to make sure (s)he can follow it. How (s)he follows it readily tells you how well it was (or wasn’t) written, what does and doesn’t work, what adjustments need to be made, and so on.

It may not even entirely be the wording that needs adjustment. How easily did the person find information within the document? Was it there but not easily found? Was it overlooked? User testing not only can determine content accuracy, it can also serve the same purpose as UX/UI in that it can determine how effective object placement and document layout is.

And like application development, user testing your documentation determines what adjustments need to be made before it’s released. Additionally, user testing isn’t just critical for development; it’s important for document maintenance as well. Documentation that hasn’t been adjusted for changed environments makes for inaccurate information. Much of that can be caught through user testing.

I’ve said time and again that document development needs to be treated the same way as application development. User testing is an important step in that life cycle. It determines that your document quality is improved when it is released. Without it, you run the risk of releasing bad, poor quality, or inaccurate documentation.

Keeping documentation simple

In my presentations, I preach that keeping it simple is key to effective technical communication. It takes effort to read (you can write this on my gravestone: reading is work!), and the less you make someone work, the more effective the document will be.

However, keeping things simple is easier said than done. Taking a complex concept and explaining it in simple terms is a skill (and it keeps me employed as a technical writer). So what can you do to simplify concepts?

Well, here’s a few tips that might help you out!

Keep it high level

This particular tip comes with a caveat: “it depends.” (If you’re a DBA, you’ll recognize this as being “the standard DBA answer.”) Among other things, it depends on your target audience, and it depends on the type of document you’re writing.

Consider the audience. If you’re writing for peers, chances are that you’d be okay with including technical jargon or abbreviations that your colleagues will understand. But if you’re writing for managers, other departments, external customers, or anyone who doesn’t understand the technology that you see regularly, chances are that you will need to keep it high level.

Most of these people don’t want to see, and often aren’t interested in, detail. I once had a manager who was fond of saying “don’t tell me how to build the clock; just tell me what time it is!” In other words, just get to the point. Don’t get bogged down in the details. Unfortunately, this is a habit that I see all too often with technologists who feel that they need to include every single little detail. Chances are, it isn’t going to be read. Don’t do it!

It also depends on what kind of document you’re writing. If you’re writing, say, a glossary of terms, a systems administration manual, or a data governance document, then yes, things will need to be spelled out and defined clearly. But if you’re writing a step-by-step guide, a checklist, or a quick-reference manual, things need to be interpreted in a few minutes, possibly even seconds. For example, if I’m writing a step-by-step guide, my rule of thumb is, if an instruction cannot be followed in a few seconds, the instruction has failed, and it must be rewritten.

Good writing matters

I said in my previous article that you don’t necessarily have to have command of a language to be a technical communicator. At the same time, the better command you have of a language, the better your writing will be.

In my documentation presentation, I cite an example of why good grammar matters. Take these two sentences which basically say the same thing, but one is written in active voice, while the other is written in passive voice.

  • The boy mowed the lawn. (Active)
  • The lawn was mowed by the boy. (Passive)

Question: which sentence is easier to read? I’d say the active voice (and I’m sure many English teachers would agree).

There are many more examples, I’m sure, where good grammar makes a difference, makes things clearer, and contributes toward more efficient writing. Bottom line: if you write well, your documentation is better.

Stop saying “PLEASE!!!” (Avoid filler words)

One of my biggest technical writing pet peeves is using “please” in technical documentation. I’ve written about this before. You are NOT asking people for a favor, you are TELLING them to do something! “Please” is a filler word that not only takes up space unnecessarily, it is downright annoying to read.

“Please,” however is not the only filler word to avoid. I don’t have a comprehensive list of words to avoid, but off the top of my head, words such as “like,” “professional,” “extremely,” and so on should be avoided. The more words that are added, the more difficult it becomes to read.

Some other statements may not necessarily be fillers, but they might not add anything, either. My advice: if you’re trying to tighten up a sentence, eliminate unnecessary words. If the sentence reads well without them, leave them out.

Use illustrations and examples

The adage that “a picture is worth a thousand words” is true! An illustration often describes a concept much better than just words can.

Which of these instructions would you rather follow? Would you rather follow this…

(Source: https://www.realsimple.com/beauty-fashion/shoes-accessories/tie-necktie)

…or this?

(Source: https://steemit.com/fashion/@ighoboss/style-made-easy-tie-knotting)

Even if I’m looking up an instruction, if it includes an example, I will often refer to the example first, and not even bother with what’s written, unless I have to glean some information from the text.

Use headings

Let me ask a question. If I wrote this ‘blog article without any headings, would you want to read it? You’d likely see lots of black text paragraphs without any idea as to what each one is about. Headings provide an overview of each section and topic. They provide a reference that’s easy for the reader to find what they want. They can even determine how a document is structured. Long story short: headings make a document easier to reference.

Let someone else do it

No, I’m not saying this as a cop-out! We all have our strengths and weaknesses, and for many people, writing and communication might not be a strength. So why not let someone else do the documentation heavy lifting for you?

Even if you’re not the one doing the actual writing, you’re still an important part of the writing process. It’s called being an SME (Subject Matter Expert). You have valuable information that you want to pass along. The writer is your interpreter. The writer will refer to you for information. (S)he will likely be asking you a lot of questions, which very much makes you part of the documentation process. Even a conductor is playing an instrument; (s)he is playing the ensemble that (s)he is directing. Being an SME is the same principle; you’re directing someone to do the actual writing.

Summary

These are only a few suggestions toward making your documentation better. There are many more ideas that I didn’t even touch, and they would likely make this article much longer than it already is.

Good documentation is essential for any business, and can often prevent issues before they arise. Keeping it simple goes a long way in making your documentation efficient and easy to follow.

Lack of language command doesn’t have to be an impediment to presenting

As someone who is a child of immigrants, I understand and appreciate the travails of anyone who is new to this country and struggles with the English language. Indeed, English can be a very screwy language, with a plethora of archaic rules such as “i before e” and so on. I remember my Korean mother telling me about how Korean is grammatically perfect; every rule is followed to the letter (no pun intended), and there is no “i before e” or anything like that. I got a better idea of this when I tried to teach myself Korean. (I’ll confess that I’ve gotten busy, and I haven’t kept on top of this as I’d like. I’ll have to pick this up again at some point.)

I’ve learned about the structure of the Korean language, but I have not learned enough to be able to carry a conversation or read signs. As such, I have absolutely no command of the language. So I respect anyone who is not a native English speaker, but learns enough to be able to come to this country and be able to have a comprehensible conversation. That ability requires a great deal of work and practice, and to be able to go to a foreign country and speak the language of its inhabitants is a tremendous achievement.

That said, a common statement among my friends and colleagues from foreign countries is that because English is not their native language, it is an impediment for them to do technical (or any) presentations. More often than not, it isn’t external feedback or reactions that keep them from presenting, but rather a self-perception that because they aren’t native English speakers, they aren’t able to present technical concepts to English speakers.

To those people, I want to tell them (hence, the reason for this ‘blog article): nothing can be farther from the truth. On the contrary, I fully encourage you to present.

Now, I was born and raised in New York State. English is my native language. I like to think that I have a pretty good command of the language, and I will confess to being a bit of a grammar snob (I’ll often joke that I’m one of those people who’s silently correcting your grammar!). Granted, I don’t pretend to be perfect, but I think I can hold my own. I will often say (and I do often say this in my presentations) that command of your native language makes it easier to present concepts when it comes to technical communication.

However, while language command is helpful for presenting topics, it isn’t a requirement. Some of the best speakers I’ve met on the SQL Saturday circuit have been people whose first language is not English. The list includes some very good friends of mine whom I’ve met through SQL Saturday, including Slava Murygin, Taiob Ali, Michelle Gutzait, Paresh Motiwala, Cecelia Brusatori, and Thomas Grohser, among others. They are all excellent speakers whom I highly recommend, and the fact that they speak with accents that may be foreign to many Americans doesn’t keep them from presenting technical topics or being group leaders.

Even if you’re an English speaker who never got the hang of diagramming sentences or knowing the difference between their, they’re, and there, it should not deter you from presenting important topics. And if you are self-aware about your lack of language command, don’t be afraid to ask for help or feedback from someone who does have a good grasp of language.

So if you have a topic to present, but you’re not a native speaker, go ahead and present, anyway! If your topic is profound, interesting, important, etc., the material will often speak for itself. Lack of language command is not an impediment for presenting.

Reminder: I’m speaking on Wednesday, October 20 #TechCon2021

I will be speaking at the Quicken Loans/Rocket Mortgage TechCon 2021 on Wednesdauy, October 20, at 3:45 pm EDT.

I will do my session about how to talk the language of technology to those who don’t understand it, called “Whacha just say?!?” This is the same presentation that I gave this past Saturday at Data Saturday #13, Minnesota!

Hope to see people there!

The myth that technical communication is a soft skill

I’ve said many times — and I still continue to preach this — that technical communication is likely the least respected of technical professions. There are very few things that piss me off more than any technical manager or developer who says, “we’re all done with the code. We have ten minutes left. Let’s write the documentation.”

If this is your attitude, you are effectively taking a crap on my profession.

This is what drives me to defend what I do, write ‘blog articles like this, and speak at events like SQL Saturday and PASS Data Summit. This is something I am extremely passionate about, and I consider this a war against attitudes that technical communication is a soft skill.

However, before I start screaming from my soapbox, let me back up a little bit. My first question to myself was, what exactly are soft skills? Sure, people will say it’s the ability to get along with other people and to communicate effectively (more on that latter part in a moment). I did a Google search and came across this Indeed article on what they say are “soft” and “hard” skills.

Let me expand on communication as being a soft skill. It’s true that the ability to communicate is definitely a skill that should be honed and polished by nearly any working professional; indeed, nearly all my presentations are geared toward professional development and soft skills. And the ability to communicate technical concepts is a skill that, I believe, every professional should develop.

But here’s where the trouble starts. Too many people — I daresay, nearly everyone who is not in the profession — lump “the ability to communicate effectively” — a soft skill — together with “technical communication” — which is a profession and a hard skill. There is a major difference between the two. And I think this is what gets us into trouble. That communication is often listed as both a soft and hard skill gets people confused. You never see “the ability to write effective code snippets” or “ad hoc engineering” listed as soft skills, and nobody ever confuses software development or engineering as being soft skills. But communication is a basic soft skill, and this is where the trouble for us professional technical communicators begins.

For starters, a well-developed technical communication project makes use of a life cycle, and — I’ve said this before — it is no different from SDLC. The processes are identical. There is planning involved. If you work in an Agile environment, you should even create tickets for the projects. I once spoke at a user group meeting where I was asked, how do you plan a documentation project? My answer: treat it the same way you would a software project (hence why I always say, “treat documentation like software”). A well-organized documentation project involves planning, building, testing, adjusting, and versioning — just like software.

Technical communication also requires certain skill sets. Anyone can communicate technical concepts. But it takes a professional communicator to organize those concepts in a way that can be used by audiences. Some of the skill sets required include, but are not limited to, design, writing skills, graphic design, information architecture, UX/UI, and a solid command of the language of your choice. These are skills that are required by professional communicators, but not necessarily by non-communications professionals who are looking to improve their soft skills.

If you don’t think technical communication is a profession, explain to me why an entire professional organization, academic degree programs, and professional positions exist for it.

Some of us sing Happy Birthday, or sing along to the radio, and some of us do a pretty good job of it — but that doesn’t make us professional singers. Likewise, many of us communicate well, but that doesn’t make us all professional communicators. While there may be some overlap, there is a big difference between effective communication as a soft skill and technical communication as a profession. Professional communicators, like other technical professionals, need certain resources in order to perform their jobs effectively. And if you refuse to recognize the level of effort and professionalism that goes into it, you are effectively disrespecting the profession.

Upcoming speaking engagements (as of 10/4/2021) #ProfessionalDevelopment #TechCon21 #PASSDataCommunitySummit #DataSaturday #SQLSaturday #Networking #SQLFamily

I’ve had quite a bit of movement in my speaking engagements list in the past few months! Here are my scheduled speaking engagements that are coming up. And I’ll admit that I’m posting this as a reminder to myself as much as anything else!

Confirmed

I am confirmed to be speaking at the following events. Note: these are all virtual events, so I will not be traveling anywhere to do these talks, other than to my home office.

  • Wednesday, October 20 or Thursday, October 21 (exact date/time TBD): TechCon ’21: If you miss my talk at Data Saturday #13, you can catch it at TechCon ’21, as I am giving the same talk!

I’ve also asked about speaking at my own user group; it’s been a while since I’ve spoken there. Stay tuned!

I’m in for a busy couple of months. Hope to catch you at one of my sessions!

October CASSUG Monthly Meeting #Networking @CASSUG_Albany #SQLServer #UserGroups

Greetings, data enthusiasts!

Our October meeting will again be online. NOTE: you MUST RSVP to this Meetup at https://www.meetup.com/Capital-Area-SQL-Server-User-Group/events/281203246/ to view the Zoom URL!

Our October speaker is Josephine Bush!

Topic: SQL Auditing

Our online meeting schedule is as follows:

  • 6:00: General chat, discussion, and announcements
  • 6:30: Presentation

We usually wrap up between 7:30 PM and 8:00 PM.

Please RSVP to this Meetup, then use the online event URL to join (note: you MUST RSVP for the URL to be visible). We will send out a meeting password as we get closer to the event.

Thanks to our sponsor, Datto, for making this event possible!