#PASSDataCommunitySummit — day 1 debrief, and what I look forward to for day 2

Greetings from Summit day 2! This morning, I’m writing from the speaker’s lounge in the Seattle Convention Center, where a number of speakers (myself included) are busy looking at their laptops. I’m not sure what the others are doing — working on their presentations, maybe? — but I know that I’m here writing in my ‘blog and enjoying a few refreshments that are provided for the speakers who partake this room and its resources.

It probably makes sense for me to talk about what went on yesterday. My session was scheduled for the very first time slot of the three days of general sessions — and, unfortunately for me, that turned out to be problematic.

I did my presentation about networking, which happens to be one of my favorite presentations to do. I enjoy giving it, I get my audience involved (there is an opportunity for my audience to do some networking themselves), and I get the impression that my attendees enjoy it as well. A big deal has been made about networking for this event — indeed, I was told that about 40% of the attendees were first-time participants, so I was looking forward to a good turnout for my presentation.

It turned out to be a disappointment. Only five people showed up for my presentation.

I had two things working against me. First, I understand that yesterday’s keynote ran over time. Since my session was at 9:30 (and I intentionally waited five extra minutes, until 9:35, to start to allow stragglers to come in), it likely interfered with my (and others’) session. Second, my room was located in a relatively-new section of the convention center, located right across the street from the main convention center, and the room was a little difficult to find.

Now, let me be clear. It isn’t so much the low turnout in and of itself that disappointed me. I’ve presented to smaller audiences before (the smallest audience I had was two people — heck, I one had a session where nobody showed up). I couldn’t care less about stroking my ego. No, I was more disappointed in the fact that, at an event where networking has been emphasized all throughout up to this point, only five people got to hear my presentation describing how to network — information that I really felt could help many people throughout this event. I felt that I had a really good message to pass along — especially to the first-time attendees — and it only got through to less than 1% of the people who are here. I had seriously expected ten times that number to show up to my presentation. That, to me, was the big disappointment.

However, attendance numbers aside, those who were there said that I gave a really good presentation. And now I can say that I am a four-time PASS Summit speaker!

There was another disappointment before that. I had signed up to attend a vendor’s breakfast. I’m not going to lie; my main (in fact, my only reason) for attending was the word “breakfast.” For a decent breakfast, I’ll spend an hour listening to a vendor’s sales pitch. But it was not to be. When I arrived, there was no food left. Apparently, when they opened the doors, breakfast disappeared very quickly. I was told they were ordering more Egg McMuffins for attendees. Um, no. Lack of planning on your part does not constitute patience on mine (at least not in this case). No food, no sales pitch. I blew off the vendor’s spiel and settled for the continental breakfast they were serving in the dining hall.

But, enough of my disappointments; let’s talk about the good stuff!

After I did my presentation, it turned out that another session that interested me was in the room next door in the next time slot. Blythe Morrow did a presentation called “How to Write a Kickass Anything.” As someone who writes for a living, the session title alone was enough to pique my interested, and she did not disappoint. There was a lot to cover — too much for me to recap — but a couple of takeaways were to come up with your own professional branding (something that I’ve already done), and that “simplicity” and “clarity” are not synonymous. In regards to the latter, for most of my technical writing career, I’ve maintained a principle of KISS. When I told Blythe this, what she told me was along the lines of “making it simple doesn’t necessarily make it clear.” That was a huge takeaway for me, and it’s definitely something I’ll carry with me moving forward.

Getting together with #SQLFamily friends after the first day!

After I did my presentation, I’ve been joking that “now that my commitment to PASS Summit is done, I could technically hop on a plane right now and fly home.” But the thing is, while presentations and learning are a big part of Summit, they aren’t the only things. I’ve often mentioned the importance of #SQLFamily. It’s a real thing. In only a couple of days here, I’ve seen so many friends whom I love dearly and don’t get much of a chance to see, except when we cross paths on the SQL Saturday circuit or at other various events. These people are important to me, and I want to spend as much time with them as I can. Last night, after the day’s sessions were over, I joined friends for some drinks at the hotel across the street, then joined a few more at the Cheesecake Factory (also across the street). My friends are very important to me, so any opportunity I can get to get together with them is cherished!

I spent some time at the exhibitor hall, where the vendors have their booths set up. I’ll admit that I look for booths with good swag and prizes to win, but it’s also important to make sure you support vendors at events like this. They are, after all, a big reason why these events exist. Vendors are big supports of conferences such as PASS Summit and SQL Saturday; without them, many of these events wouldn’t exist.

One of the big booths was Redgate (of course; they’re the ones who are responsible for coordinating Summit), and they did an interesting promo. They handed out these little mini Lego Steves (see the pics below). If you took a Twitter selfie with Lego Steve, you had a chance to win a prize! I took a couple of selfies, including the ones you see below. Honestly, it doesn’t matter whether or not I win, but I thought it was fun to take these pics!

A Lego Steve, along with the contest instructions
Me, Lego Steve, and actual Steve! (Lego Steve is the one I’m holding in my fingers!)

This morning, I woke up at 4 am (local time), before my alarm went off. I got up, showered, dressed, and went to the convention center.

Bob Ward moderates the Microsoft Q&A breakfast

My first order of business was breakfast. I attended the Microsoft vendor breakfast — and yes, this time, there actually was breakfast. I got myself a good breakfast and listened to a Q&A with some Microsoft bigwigs. Bob Ward was the session moderator.

Now, a little explanation is in order. Bob Ward is probably the Elvis Presley of SQL rockstars. He is very well-known throughout the SQL community. He has written books, he has been on the front lines of SQL Server development, and people flock to his presentations when he speaks.

That said, he has one flaw. He’s a Dallas Cowboys fan. He’s such a big fan that he has been known to incorporate the Cowboys into his presentations. In fact, SQL Server 2022 was code-named “Dallas” because of him.

Because of this, I asked for the mic (I was the first to do so), and I asked this question.

“My question is specifically for Bob. What’s the over-under on the number of wins the Cowboys will have this year?”

Yeah, I know, but I had to ask. It got a good chuckle from the crowd!

After the breakfast, I attended the morning keynote, where a number of people from Redgate, including my friends, Steve Jones and Kathi Kellenberger, got to speak! I couldn’t tell you everything they discussed (I couldn’t remember it all if I tried), but Steve did mention (and I’m mostly paraphrasing here) that we are now living in a multi-database platform world, and that isn’t going to go away.

And now, here I sit, writing a ‘blog article. There are a few more sessions I want to attend, and they look like good ones! I’m looking forward to seeing what Day 2 brings!

Advertisement

Your User Manual

As a technical writer, anything that mentions “manual” (or “documentation”, for that matter) tends to catch my eye. I suppose it’s an occupational hazard. But when I saw this post from my friend, Steve Jones, it made me take notice.

I’m reblogging this for my own personal reference as much as anything else. Suppose you had a set of instructions for yourself? How would it read?

I might try this exercise for myself at some point, but for the moment, read Steve’s article, and see if you can come up with your own manual for yourself.

Voice of the DBA

Many of us have spent time looking through manuals or the documentation for some software or product. I know I’m on the MS docs site regularly for work, and there is no shortage of times I’ve used various manuals to help me fix something around the house. We usually use a manual when we want to learn how something is supposed to work, or how to get it to do what we want.

I saw a post on a personal user manual that I thought was a good idea for some people, maybe many people. This isn’t a manual for how you should live your life or work, but rather, how others might interact with you. This manual describes how you work, what motivates you, stimulates you, what pleases you, and even the environment in which are most productive.

Whether or not this is something you might give to co-workers…

View original post 299 more words

I’m speaking next weekend — in person! #WELocal

Time to get back on the road for the speaker’s circuit again!

I am speaking a week from tomorrow (April 9)! I will be in Buffalo, NY for the WE Local Buffalo conference, hosted by the Society of Women Engineers!

I will be doing my original presentation that kicked off my public speaking endeavor: “Whacha just say? Talking technology to non technical people“! I’m scheduled to speak at 2:15 pm next Saturday (click here for a PDF of the conference schedule).

This will be my first in-person event since SQL Saturday Rochester in 2020, right before the pandemic started! I’m very much looking forward to this trip, as I enjoy traveling! I’ve spoken at a number of virtual events since I went to Rochester, but they’re just not the same thing. I’m looking forward to being able to shake people’s hands (or give fist/elbow bumps, if they’re still anxious about spreading germs), handing out business cards, and taking in the local culture. I’m always game for a plate of Buffalo wings! (My wife and I were in Buffalo last summer, and we made it to the Anchor Bar. I’m hoping to sample some Duff’s this time around!)

Hope to meet you in Buffalo next weekend!

Upcoming speaking engagements (as of 1/20/2022) #ProfessionalDevelopment @SWEtalk #WELocal #Networking #SQLFamily

It’s been a while since I posted a speaking schedule update, and I figured I was overdue.

Right now, I have only one confirmed speaking engagement: the WE Local Conference in Buffalo, NY on April 8-9. Last I checked, the conference schedule still hasn’t been released, so I don’t know if I’m speaking on April 8 or April 9 (all I know is that I’m speaking!). I’m still waiting for the schedule to come out before I make my travel plans!

This will be my first in-person speaking engagement since Rochester SQL Saturday back in February, 2020, just before the start of the COVID pandemic; every presentation I’ve given since then has been virtual. It’ll feel good to get back on the road again!

Hope to see you in Buffalo in April!

An introduction to the C4 model

The C4 Model for Software Architecture
(Image source: The C4 Model for Software Architecture)

This week, I was introduced to a new (to me) methodology called the C4 model. Now, in this context, C4 does not refer to the high explosive. In this case, C4 refers to a development methodology. Mostly, it refers to software development, but it has other applications as well, and that includes document development.

As part of my indoctrination into this methodology, I was provided this link. So far, it looks like an interesting read. I’m still reading about it, but here’s my understanding of the methodology thus far.

First of all, C4 stands for context, containers, components, and code. Think of it as looking at something at four different levels, from the top level (context) that shows the big picture, all the way down to the most minute detail (code).

The top level (context) refers to the big picture. Using maps as an example, here is a map of the United States — for purposes of this example, the big picture. You’ll notice that I drew a black box around New York State, which indicates the next level to which I will zoom.

If we want to drill down to the next level (container), a state would be the next logical level. So for the next map, I’m drilling down to my home state of New York. Again, I’m drawing a black box around the area to where I will drill down next.

A city or region is the next logical step (component). Let’s drill down even further, this time to my home city of Troy. Again, I’m drawing a black box around the next level to which I will zoom.

The bottom level of this methodology (code) shows the minute detail. For personal privacy reasons, I’m not using my home location, so instead, I’ll use one of my favorite establishments: Brown’s.

You’ll notice that I did not draw a black box in the last illustration; this is because we are at the lowest level in this model. I suppose if I really wanted to get granular, I could drill down into building floor plans, but for the purposes of this example, I think the point is made.

From how I understand it, the C4 methodology appears to be used for diagramming and documentation. It addresses a shortcoming in many technical diagrams in which they can be confusing and difficult to follow. C4 addresses this by showing how components relate to the big picture.

While I haven’t (yet) come across this in my reading, I want to note something that I think is important. When I captured the maps you see above, I thought it was important to highlight the context to which each level was related. If you look only at the bottom code level, you only see a building and a street (although I did make it a point to also capture the street name and route number). If you don’t know what city or state this place is located, then this macro level is likely useless information. The same is true for technical documents. Each small piece fits into a larger puzzle. If you don’t understand how the puzzle piece fits, you don’t get a sense of how the piece relates to the rest of the puzzle, and it becomes confusing and hard to follow.

As I said, I’m still reading about this, so I’m not yet sure what additional intricacies about the methodology I need to learn. Nevertheless, the concept does sound interesting, and I’m looking forward to learning more about it as I improve my skills as a technical communicator.

Some links, for your (and my) reference:

#WELocal Conference, Buffalo, NY — I’m speaking!

I received word that one of my submissions has been accepted for the WE Local Conference in Buffalo, NY on April 8-9! The WE Local Conference is sponsored by the Society of Women Engineers. This is my second conference that is not related to PASS where I’ll be speaking, and this will be my first in-person event since SQL Saturday in Rochester, just before the pandemic hit.

I will be doing my presentation about communicating to non-technical people (my original talk)!

So meet me in Buffalo next April for what looks to be another great conference! And perhaps you’ll be able to catch my presentation, along with a plate of Buffalo wings!

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.

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.

When information is overlooked

I went grocery shopping the other day. I picked up what I thought were two identical bottles of salad dressing (in the photo above). I remember thinking how strange it was that they put the same bottles of salad dressing in two different spots on the shelf. Nevertheless, I took one from each side and tossed them in my cart. It wasn’t until much later, after I was home, when I looked in the pantry, saw the two bottles sitting together on the shelf, and realized that one was organic, while the other was not.

To be honest, I really couldn’t care less as to whether a food product is organic or not. I usually buy the regular product because it tends to cost less and usually has a longer shelf life. (Personally, I believe the purported health benefits of organic products are minimal and overhyped, but I digress; that’s not what this is about.) But what I am wondering is how I was blind to the fact that one said “organic” while the other didn’t.

I’m sure there are cognitive and behavioral studies as to why people are blind to certain pieces of information, but that’s a topic that goes beyond my level of knowledge or expertise. (Before anyone says anything about information bias, I will mention that while I do tend to buy non-organic products, I really don’t have a strong bias one way or the other.) Rather, what I’m writing about is the fact that information can and does get overlooked. So what do technical communicators and UX/UI designers do to combat this?

For starters, I’ll say that the fact that information is missed is a matter of when, not if. Using myself as an example, I’m the first to admit that I often have the attention span of a flea, and as such, I’ll often skim, as opposed to deeply read, documentation that isn’t my own. As such, I’ll often overlook information. Granted, many people are more thorough than I am, I’m sure, but I guarantee that everyone will miss at least one thing. We are humans, not computers, and we are not capable of scanning, parsing, and processing every little bit of information that comes our way, so it’s unlikely that we’ll absorb or retain everything that’s thrown at us.

This brings me to another of my mantras: reading is work. (You can put this on my gravestone.) Reading requires effort. The more effort that is required, the more something is likely to be missed. One of my biggest documentation pet peeves is anytime someone says “it’s right there in the documentation,” but when you look at the documentation, the information is buried like a Where’s Waldo puzzle. Nobody can be expected to find information like that, and people who insist that that is valid documentation are not, in my honest opinion, technical communicators. Bottom line: if you have an important piece of information, don’t expect it to be read if you bury it within bad design or a large black paragraph swath.

However, that wasn’t the case with the bottle of salad dressing. The bottle was clearly marked. Yet I didn’t notice it until I got home. So what can writers and designers do to mitigate missed information? I don’t know if I have the answers, but I do have some ideas.

For starters, placement matters (good designers understand this). I admit that I was confused that these bottles were on opposite sides of the same shelf. Maybe this wasn’t enough. Placing them on separate shelves likely would’ve helped. Or, maybe separating them a little from the other group of bottles (the documentation equivalent would be utilizing whitespace). Maybe even placing the bottles in a separate section dedicated to organic products might’ve made a difference as well.

Another idea would be to use different appearances, such as varying fonts, graphics, or colors. As you can see in the above photo, both bottles use white labels and feature a picture of a peach. That design led me to believe the products were identical, but yet, I completely ignored the fact that one said “organic” while the other didn’t. We often comprehend visual cues before text, so changing the picture or the label color likely would’ve been enough for me to differentiate them at a glance.

I’m sure there are other ideas as well, but the bottom line is that information can and will be overlooked. By considering better information design, the chances of information being overlooked can be minimized.