Always ask someone to test your product

This morning, one of my colleagues posted this message to our Slack channel:

please ask someone else to test your code before pushing it

It brought to mind an important thought (and more ‘blog article fodder): any time you produce something, regardless of what it is — a software application, documentation, a presentation, a music composition, a dish you cooked, etc. — always ask someone else to test it out before you send it out for public consumption.

That testing could take several different forms — it could be an end user trying your application, somebody reading your document, listening to your presentation or your music, trying your dish, and so on.  Testing results in feedback, which results in improvements to your product.

Whenever we produce something, we have our own vision — and our own biases — as to how the product should come out.  We expect our products to be perfect as resulting from our own visions, and we expect (and demand) that the consumers adhere to our visions and how we expect the products to be viewed or interpreted.

Unfortunately, we are blinded by our biases.  The world does not share our same visions.  People who use our products will never, ever, perfectly interpret how our products should be consumed.  More often than not, we’ll find that what we produce will be used or interpreted in ways that never occurred to us.

Even in my own workplace, I write and edit a lot of online documentation.  Much of what I write comes from other sources, often about topics about which I know little (or, sometimes, nothing).  I try to write material based on the information I have at hand.  Very often, I come across gaps that need to be filled.  I’ll do my best to ask original authors what was intended, or to dig for information to fill those gaps.  But in absence of those resources, I end up making assumptions and using my own intuition to fill in the blanks.  Those assumptions might not necessarily be correct, and what I write could end up being different from what was originally intended.  It is for this reason why I am constantly asking my colleagues, “take a look at what I wrote.  I want to make sure what I wrote is accurate.”

In a manner of speaking, creating products is a form of communication — in that what we produce results from an idea in our heads, and the end users — the consumers — are the ones “listening” to the communication — in this case, the end product.  If you are familiar with the basic communication model, a sender creates a message, a receiver interprets the message, and the receiver reacts to the message in the form of feedback.  Producing a products works in exactly the same way — a producer creates a product, a consumer uses the product, and the consumer reacts to the product, generating feedback.  In between the sender and the receiver is “noise” that degrades the message or the product (it is not literally noise — the “noise” can simply be the fact that the sender’s and receiver’s interpretation of the message are not one and the same).

So, any time you create some kind of product, always ask someone else to try it out.  You’ll find that the person’s feedback will result in tweaks to your product.  And you will end up with a better product.

Advertisements

My first featured podcast!

My podcast is now online!  Check it out!

My first podcast interview!

About a week ago, I received an email from Carlos Chacon of SQL Data Partners inviting me to take part in a podcast.  This was my first such request, and I jumped on the opportunity.

The podcast recording took place last night.  My topic was along the lines of “writing and communication: why it matters to data professionals.”  It was a lot of fun, and I very much enjoyed talking to Carlos and his partner, Steve.

The podcast should air sometime in March.  It will be posted on their ‘blog.  When it does, I’ll make sure that I post a link to it!

What are effective communication skills?

I cam across this article on Grammarly, and I thought it spoke volumes — enough that I’m sharing it in this ‘blog article.  Read and enjoy!

Writing blind

“Life is like a sewer.  What you get out of it depends on what you put into it.”
— unknown

As a technical writer, one thing I often request is access to the product — whether it’s a web site, application, device, tool, etc. — that I’m writing about.  In order for me to write something about a product, I need to know what the product is, how it works, and how to use it.

Unlike, say, a novelist or a creative writer, technical writing topics usually do not originate from the writer, but from something or someone else, such as a process, procedure, or product.  In order for the writer to produce a good, quality document, he or she must know about it — what it is, why it’s significant, what it looks like, how to use it, potential issues, and so on.

What happens, however, when the only resource you have is someone else’s description?  Moreso, what happens when that person is (by his or her own admission) not a writer?  (There’s a reason why this person gave you this project in the first place.)  I recently worked on a small side project that reminded me just how important this is.  Granted, it was only a small and minor project, but it did remind me about just how critical it is for a writer to understand the subject.

Imagine the following situation: you need to add more windshield washer fluid to your car.  You open the hood and see different caps.  You know there are caps for washer fluid, engine coolant, oil, and so on.  However, they are not clearly marked (as far as you can see), and you don’t know which one is which.  Opening the wrong cap and filling it with the wrong fluid will damage your car.  You call a friend who tells you to look for a plastic reservoir filled with blue liquid.  Trouble is, there are two of them (one is washer fluid, the other is coolant).  Your friend tells you to look for something that looks like a windshield on the cap.  Okay, you see something that looks like it might be a window with a wiper going across it.  That’s it.

Sound frustrating?  These are the kinds of situations that technical writers and communicators deal with regularly and on a much larger scale.  In order to write a technical document, the writer must have a source of good data — whether it’s hands-on experience, pictures, data graphs, good descriptions, etc. — in order to write a quality document.  A bad or inaccurate source of data will often result in a bad document.

Developers, coders, and data professionals have a name for this kind of situation: garbage in, garbage out.  In order for data to be processed into information (I won’t get into it now, but there is a difference between data and information — that’s another topic for another time), you need to have good data to start.  Bad data results in bad and inaccurate information.

Writers cannot read minds.  Unless a subject matter expert (SME) can properly convey his or her idea (and it almost never happens on the first go-around), it might take several iterations and lots of SME-writer interaction before the draft is correct.

Professional chefs have a term for ensuring everything is set up and in place before cooking: mise en place (pronounced “MEES-in-plahs”).  While the technology sector does not use the same terminology, the principle still applies: make sure things are in place and ideas are properly conveyed before information processing (including documentation) can occur.  Otherwise, trash at the beginning of the process will likely result in trash at the end.

SQL Saturday #694, Providence

This morning, I saw a ‘blog post from my friend, Greg Moore, who wrote about his upcoming presentations at SQL Saturday in Washington, DC this Saturday.  Greg is an excellent presenter, and I always recommend his presentations anytime.

It also made me realize a few things.  First, my own SQL Saturday presentations are coming up quickly — this Saturday (December 9), in fact.  Warning: dates in calendar are closer than they appear!  So I figured I should do more to promote my own presentations.  Come hear me speak at SQL Saturday #694 in Providence, RI.  I will be giving the following two presentations:

Providence SQL Saturday is a special one for me.  I first spoke at Providence two years ago, and it represented a couple of milestones.  First, it was the first SQL Saturday I ever attended that was outside New York State.  The first ones I attended were all in New York City (and to this day, I still try to attend that one whenever I can, regardless of whether or not I’m speaking) or in Albany.  Second, it was only the second time that I had ever presented at a SQL Saturday.  The first was earlier that summer, when I spoke at my hometown SQL Saturday in Albany, NY.  In fact, the presentation I gave — talking to non-techies — is the same one that I will be giving this Saturday.  I’ve since added to it and polished it a bit.  Hopefully, this presentation will go even better than the last time I gave it in Providence two years ago!

If you’ve never been to a SQL Saturday, check it out.  It’s a great day of learning (and it’s free — although there’s usually a nominal fee for lunch), it’s a great opportunity to network with industry colleagues, and it’s a fun social event (seriously, it is)!  I look forward to every SQL Saturday that I attend, and this Saturday should be no different.

Hope to see you there!

Upcoming SQL Saturday dates for me

Looks like my SQL Saturday schedule will be busy!  Here are my upcoming dates (and I admit that I’m writing this for my own reference as much as anything else).

Scheduled to speak

I am scheduled to speak at the following event:

Presentation abstracts submitted

I submitted my presentations to these events; no guarantee that I will be picked to speak at any of these, but you never know:

Save the date

Event that is on the calendar, but not yet scheduled (hence, there’s no link to it yet); I intend to submit to it when it goes live:

  • July 28, 2018: Albany, NY (my hometown SQL Saturday!)

SQL Saturday is a great, free conference for anyone who wants to learn more about SQL Server.  Many interesting topics are presented, it’s a great opportunity to network, and it’s a lot of fun!

Hope to see people there!