Want to learn about a topic? Try writing about it

Every now and then, I’ll peruse the forums on SSC.  In addition to people answering questions about SQL Server, there also tends to be some banter, which is probably not unusual in many forums of this nature.  One of the comments I’ve seen time and again is something like, “I learn more about subjects by answering people’s comments on these forums.”

There is more truth to this statement than people realize.  In my experience in writing about technology, I often find that I end up learning about the technology about which I’m writing — sometimes to the point of becoming a subject matter expert.

Several years ago, I taught part-time at a local business school (roughly equivalent to community college level).  I taught primarily general mathematics and a few computer classes.  I was once asked to fill in for another instructor who taught statistics.  My problem: I didn’t know much about statistics.  So, I read up on it (along with the syllabus that I would be teaching that day).  I wanted to at least be able to sound like I knew what I was talking about.  As it turned out, by teaching that class, I actually learned something about it.  The students were not the only ones who got an education that day.

The other day, I began writing a draft article regarding a subject about which I’d like to learn more: BI (edit: the now-finished article can be seen here.).  I’ve dabbled in BI a little bit; I worked a previous job where I was asked to perform some data analysis (which is how I learned about cubes and pivot tables), and I took a course in decision-support systems in grad school.  I’m seeing more SQL Saturday presentations about BI; indeed, there are even SQL Saturday conferences dedicated to BI topics (usually indicated by the words “BI Edition”).  It is a topic about which I do have some interest, and it’s something about which I’d like to learn more.

My friend, Paresh Motiwala, who was one of the organizers for SQL Saturday Boston BI Edition a while back, encouraged me to apply to speak at the event.  I said to him at the time, “the only thing I know about BI is how to spell it!”  (His response: “Hey, you know how to spell SQL!”)  On hindsight, I probably should have applied; it turns out that even BI Edition conferences accept professional development topics, under which nearly all of my presentations (so far) are categorized.

So if I claim to know so little about BI, why did I decide to start writing about it?  Well, I’m trying to learn about it, and I’d like to pass along what I learn.  But, I want to place a greater emphasis on the first part of that statement: I’m trying to learn about it.  Writing about it makes me learn something about it a little more in-depth.  And by doing so, I discover that I have a better grasp of the topic.

Hopefully, relatively soon, you’ll see an article from me about BI.  Hopefully, I’ll have learned enough writing about it that you’ll be able to learn something from me.  And hopefully, I’ll have demonstrated that I’m learning something new, and improving myself in the process.

If you want to learn something new, try teaching it or writing about it.  You’ll be surprised how much you, yourself, learn in the process.

Advertisements

Better Comments

This is a reblog of a post by my friend, Steve Jones. I’ve often said that commenting code is a form of documentation, and needs to be done more.

Voice of the DBA

I assume most of your comment your code.

Well, you probably comment code most of the time.

I’d bet your comments have quite a bit of detail.

And you do this completely inconsistently.

That’s what I’d think, or maybe just what I want. Even the best developers I know will not consistently comment code. You can drift through any project on Github and see this. Those projects on GitHub might even be better documented because people know they are public. In most corporate environments I have worked in, I’ll find that when people get busy, or distracted, or even when they’re experimenting to find a solution, and they don’t write detailed comments. Usually only when someone fixes a bug, with a solution found quickly, do I get a really useful comment.

There are all sorts of ways that people think about commenting their code. I ran across a post from…

View original post 254 more words

Definitions that aren’t

This is yet another item that can be listed under tech writing frustrations.

I was working on a project where we needed to rewrite a set of glossary definitions.  I won’t go into the definitions (primarily due to corporate privacy), but for illustration purposes, let me use this analogy.

Let’s say you’re looking up a definition for, say, a car.  You come across the following glossary listing: “A car has four wheels.  It is made of metal.  It is not a boat.”

This tells you about some of a car’s attributes (four wheels, made of metal) and what it isn’t (a boat).  It never tells you, in any way, shape, or form, what a car actually is!

Yet this horrifically-written glossary is entirely made up of “definitions” (and I use the word loosely) written just like this.  I don’t know about you, but my assessment of these glossary definitions would be “totally useless.”

I come across “definitions” like this more often than I want to say, and they make me cringe.  People look up word meanings to find out what words mean.  Writing a “definition” that describes only its attributes is useless.  If a glossary “definition” does not “define” what it is, then it does not do its job.

Keeping it simple: it can get complicated

“Everything should be made as simple as possible, but not simpler.”
— Albert Einstein

“If you can’t explain it to a six year old, you don’t understand it yourself.”
— also supposedly by Albert Einstein

If you’re on Facebook, I’m sure that you’ve seen the memes that go something like this: “tell a sad/scary/happy (whatever) story using only four words.”  It’s hard to do, isn’t it?

Welcome to the world of technical communication.  One communication tenet that I constantly preach — and you’ll hear me talk about this time and again in my presentations — is the KISS principle: “Keep It Simple, Stupid.”  Ask anyone involved with technical writing, documentation, or professional communication, and I’ll bet that most, if not all, of them will mention the KISS principle in some way, shape, or form (maybe not in those exact words, but you get the idea).  The goal of communication, after all, is to transmit information from a sender to a receiver.  If the message being conveyed is easy enough for the receiver to understand, so much the better.

However, here’s the irony: making things simple is difficult!

How often have you been asked to write something for knowledge transfer, and ended up with something that was nearly incomprehensible?  (Don’t be afraid to admit it; hey, I’ve done that, too!)  Whenever we’re tasked with writing documentation, our tendency is to explain every little tidbit of knowledge that’s in our head.  When that happens, we end up writing a huge paragraph of black text that nobody — and I mean, NOBODY, including yourself — wants to read!  That is not conveying information; that is obfuscation.

So how do we go about making things simpler?  For starters, I discuss some ideas in my previous articles about designdocument frustration, using examples, and talking to non-technical people.  I won’t rehash them here; I’ll leave it to you to go back to read those articles.

Additionally, here are some more thoughts that might be helpful.

  • Include only information necessary for the task at hand.  Avoid the tendency to include every last detail.  As a former manager was once fond of telling me, “don’t tell me how to build the clock; just tell me what time it is!”  I also remember a time back when my father was first learning about PCs.  He kept asking me questions about how the CPU and memory worked.  I finally said in frustration, “you don’t have to know how an internal combustion engine works in order to drive a car!”
  • Put yourself in the reader’s shoes.  When I wrote one of my very first technical documents, I said to myself, “okay, let’s say I’m the night operator who needs to use this document.  What do I want to see that would help me?”  That mindset resulted in a very successful document.  Reader empathy goes a long way.
  • I’ve said it before, and it’s an old but true saying: a picture is worth a thousand words.  A good illustration can convey a concept that’s difficult to do in words.
  • Avoid using long (or multiple) words when a simple (or single) word will do.  I think this is self-explanatory.
  • Voice matters.  Below are two sentences, one using active voice and one using passive voice.  Question: which one is easier to read?  Advice: try sticking to active voice.
    • Active: “John mowed the lawn.”
    • Passive: “The lawn was mowed by John.”
  • Formatting is a big deal.  Check out documents that you found easy to follow.  Pay particular attention to paragraph length, whitespace, headings, and so on.

People — myself included — say that the easier you can make things, the better.  The fact is, we humans only have a limited attention span, and we neither have the time nor the patience to comprehend complex information.  Simplifying things helps — but it’s also hard to do.  If you ever believe you know a lot about a concept, try explaining it to a child — and see for yourself how easy it is.

Setting a good example

I was recently tasked with a project where I would be assisting with developing a data governance document.  Trouble is, I have no idea what a data governance document is supposed to look like.  I looked at what my colleagues had written so far; what they had written looked pretty good, but it still didn’t really give me a good idea as to what the end product would eventually look like.  So I ran a Google search for “data governance document examples.”  Among other things, I came across a PDF document by the Federal Highway Administration, which includes a section called “Data Governance Plan.”  Okay.  Now I have something to go by.

How often have you heard things like “set a good example,” “let’s look at this example,” or “here’s an example of…”?  Whenever I need to look something up, more often than not, the last thing I use is a dictionary definition, or syntax description.  Most times, the first thing I’ll look up is an example of what I want.

Let’s see an example of — well — an example.  More often than not (as I’m sure most of you do), I’ll need to go online to look up things I don’t know very well — like, say, function syntax.

Let’s take, for example, a simple SQL SELECT statement.  I looked up the SELECT statement on MS Books Online and came across this syntax definition.

-- Syntax for SQL Server and Azure SQL Database

<SELECT statement> ::= 
 [ WITH { [ XMLNAMESPACES ,] [ <common_table_expression> [,...n] ] } ] 
 <query_expression> 
 [ ORDER BY { order_by_expression | column_position [ ASC | DESC ] } 
 [ ,...n ] ] 
 [ <FOR Clause>] 
 [ OPTION ( <query_hint> [ ,...n ] ) ] 
<query_expression> ::= 
 { <query_specification> | ( <query_expression> ) } 
 [ { UNION [ ALL ] | EXCEPT | INTERSECT } 
 <query_specification> | ( <query_expression> ) [...n ] ] 
<query_specification> ::= 
SELECT [ ALL | DISTINCT ] 
 [TOP ( expression ) [PERCENT] [ WITH TIES ] ] 
 < select_list > 
 [ INTO new_table ] 
 [ FROM { <table_source> } [ ,...n ] ] 
 [ WHERE <search_condition> ] 
 [ <GROUP BY> ] 
 [ HAVING < search_condition > ]

Is this correct?  Sure.  But how well can you follow it?  For example, what is significant about items in square brackets (“[]”)?  What about items in angle brackets (“<>”)?  How about the pipe character (“|”)?  It takes some time to understand or follow what they’re trying to tell you.  Maybe it’s helpful when you’re trying to understand a concept, but when you’re trying to understand something quickly, this might not work very well for you.

On the other hand, when I scrolled down on the page, I came across a few examples.  Here’s one that illustrates the HAVING clause that I randomly grabbed from the page.

SELECT OrderDateKey, SUM(SalesAmount) AS TotalSales 
FROM FactInternetSales 
GROUP BY OrderDateKey 
HAVING OrderDateKey > 20010000 
ORDER BY OrderDateKey;

Looking at the example, how much better can you comprehend a SELECT statement syntax?  For me, personally, the example works much better than the statement syntax above; I understand the syntax much better by the example than I do by the syntax definition.

How about something for those of you who don’t understand SQL and have no idea what I wrote above?  What about something like, say, a word pronunciation?  I tried to think of a difficult word to pronounce.  I figured the last name of Duke basketball coach Mike Krzyzewski would be a good one.  Wikipedia lists the following for pronouncing his name: “/ʃɪˈʒɛfski/” and “shih-ZHEF-skee.”  Can you easily use /ʃɪˈʒɛfski/ to pronounce his name?  Probably not.  You need an understanding as to what the pronunciation symbols mean.  Granted, clicking it brings you to a pronunciation guide that explains it.  But even so, you still need to look up the symbols, and you need to figure out how to use the guide.  That takes time and effort.  On the other hand, most native English speakers can look at “shih-ZHEF-skee” and have a pretty good idea as to how to pronounce Krzyzewski.

I’ve written in previous articles (check out my articles on tech writing frustration, design, and talking to non-techies) that illustrations are worth a thousand words.  Examples are types of illustrations.  While examples may not necessarily be pictorial, they serve the same purpose: illustrating a concept in a way that’s easier to grasp than just a definition.

We’ve often been told that we should “set a good example for others to follow.”  That’s usually said in the context of how we behave.  However, it can also apply to how we communicate as well.

The art of talking technology to non-technical people

“Eschew obfuscation.”
— unknown

Let’s discuss how to tie a tie.  First, you take the tie and put it around your neck, making sure that it lies within your shirt collar.  Make sure the seam is facing toward your body, and the wider end of the tie hangs down roughly two-thirds of the length of the tie.  In other words, the wider end should hang down farther than the narrower end.  Take the larger end over the narrower end.  Wrap it around once so that it forms a knot.  Take the larger end and put it through the knot you created.  Once that’s done, pull it tight.  Adjust your tie by pulling on the narrow end, which should now be behind the wide end.  Your tie should now appear neat and flush against your shirt.

Raise your hand if you actually followed the above paragraph.  And when I say “followed,” I mean that you read (as opposed to skimmed) through the entire paragraph, following every step and not falling asleep while reading it.  I’ll bet that not a lot of hands are up.

Yet this is exactly the way that so many technologists tend to write when they are asked to convey a set of instructions.  They will write (or talk) in lengthy detail, explaining every little thing and believing that the reader (or listener) is soaking up every detail and is in rapt fascination of the subject, holding on to every single word.

Oh, if only that was true.  If that was the case, we wouldn’t have technical writers.

I wrote a couple of articles a while back about tech writing frustration and why design matters.  They provide some thoughts that are directly related to this article, so I suggest you read them before continuing with this article.  If you haven’t read them yet, check them out.  Go ahead.  I’ll wait.

At this point, I’m trusting that you understand at least some of the principles behind good writing and design.  (If you don’t, and you didn’t read those previous articles, shame on you.)  Many, if not all, of them come into play when talking about talking to a non-technical audience.

Giving (and taking) instructions is hard

Let’s talk about that initial tie instruction paragraph for a moment.

This is a demo I use in two of my presentations.  I ask for a volunteer, preferably someone who does not know how to tie a tie.  I hand him or her a tie, and give that person simple instructions: “put it on.”  Of course, if the person doesn’t know how to put on a tie, he or she is likely to struggle doing so.

At that point, I get the rest of the audience involved.  My instructions to the rest of the group: “you folks are the help desk.  Tell this person how to put on the tie!”

I’ve done this demo to varying degrees of success.  In some cases, the audience does a very good job of explaining how to tie the tie, and it ends up looking pretty good.  I’ve also seen demos where my volunteer looks like he or she tried to tie the tie using only one hand, two fingers, and blindfolded.

The point of this exercise is to demonstrate that giving and receiving direction is difficult.  A lot of people mock tech writers, thinking that writing step-by-step instructions is no big deal.  But after putting people through this exercise, they usually end up singing a different tune.

Be patient!

When you’re talking to a non-technical audience, patience is a vital virtue.  People can be intimidated by technology, and lack of patience on your part will only do more to add to their discomfort.  Bear in mind that your audience is not as tech-savvy as you are, and will likely not have a grasp of technological concepts.

Any time you try to do a task you’ve never done before, how do you feel?  Most likely, you’re going to be at least a little nervous.  These people are likely to feel the same way.  Telling them to “click Enter” might as well be telling them to hit the gas pedal while they’re blindfolded.

Speaking of clicking Enter, don’t take for granted that people might not know what some technologies are.  I’ve heard stories of people using mice to different degrees, including using them as foot pedals and holding them up to the screen.  (And by the way, I’m sure you’ve heard the joke about not being able to find the “any” key.  I can tell you from firsthand experience that those are not jokes — the stories are true!)

What you see may not be what the audience sees

I’m sure you’ve seen the classic image below.

rubingestalt

What did you see first: a vase or two faces?  Perspectives matter, and it happens all the time when trying to explain technical concepts.  Don’t assume that your audience sees the same thing that you are.  Even if you and your audience are looking at the same screen, what you and your audience see might not be the same thing.

Having said that…

A picture is worth a thousand words.

Very early in my professional career, I was tasked with writing a document for the nighttime support staff, explaining how to support a WORM drive.  When a customer requested data from an optical platter that was not in the drive, the user needed to insert the new platter into the drive.  I could have written an instruction saying that the A side had to be up, with the A label on the left edge, and the disk slide facing away from you as you put it in the drive.

Instead, I opened my very primitive paint program and drew something similar to this:

disk

Suddenly, the instructions were clear.  The document was successful, and the operators were able to follow it to perfection.

However, be careful — there is a wrong way to use illustrations!  Imagine, for example, that you’re trying to find a Little Caesar’s Pizza or a Home Depot.  You find a site that has a map.  The problem is, the map is an image that’s zoomed in (with no way to expand the map).  The image looks like this:

map

Tell me, on what street are these places?  For that matter, in what city, state, or even country are these located?  There’s no way to tell, because there is absolutely no point of reference or context to this illustration.  A picture might be worth a thousand words, but if you’re not careful, it could be worth exactly zero words.

Use analogies

I once sat in on a SQL Saturday presentation by Thomas Grohser where he was talking about SQL data storage systems and data access.  I’ll admit that I had a hard time following some of what he was saying, until he gave the following analogy:

“Imagine you get on an elevator with ten people.  Each person presses a different button.  Now imagine that the elevator has to go to every floor in the order that the buttons were pushed!

Suddenly, Thomas’s concept was crystal clear!

Another time, I was speaking to a co-worker who had tried to explain to someone that she was trying to store more data on a disk than there was space on the disk.  (This person did not understand that data takes up disk space.)  I told him, “you should’ve said that you can’t put ten pounds of stuff* into a five pound bag!”

(*Okay, I didn’t say “stuff!”)

The moral of the story is that analogies are highly effective in communicating concepts.  If you can effectively explain a concept using an analogy (note: make sure the analogy you’re using is business-appropriate), then go ahead and do so.

KISS!  KISS!  KISS!!!

No, I don’t mean hanging out with your sweetheart.

Make sure you follow the KISS principle: KEEP IT SIMPLE, STUPID!

Technical instructions need to be kept simple.  A lot of technologists don’t understand that reading is work!  It takes work to read and comprehend a paragraph.  What if a set of instructions needs to be understood quickly?  If a person needs to take a minute to figure out what is being said, that’s a minute that was just wasted.

Generally, the rule of thumb I use is, if it takes more than a few seconds for a reader to understand my instruction, then my instruction has failed.  Don’t make the reader have to work.

Realize that this will not happen overnight

Now that I’ve gone through some of the suggestions for talking to non-technical people, understand that not everyone has the ability to convey technical information in a manner that can be understood, and being able to do so won’t happen overnight.  Like everything else, it takes time and practice to get that skill down.

In any case, hopefully, these tips will help you become a better technical communicator.  In the long run, this ability will enhance your skill set — not just as a communicator, but as a technologist as well.

Who owns the email?

A while back, one of my work colleagues asked a very interesting question.

“When we send out an email, who owns the copyright?  Is it the owners of the data (i.e. individual clients), or is it the owners of the email (i.e. our employer)?”

He continued to lay out the scenario: “Send it to Client 1. Employee at Client 1 leaks the contents of the email; (our company) has to then cede coypright (sic) to the report so that they can distribute it internall?” (sic)

His final comment: “Imagine if (other companies) did that: ‘You wrote this with Office 365, Microsoft Owns (sic) the copyright'”

That’s a good question.  It’s one to which I don’t have an answer.  To be honest, I don’t have the knowledge or background to be able to answer it.  (Maybe someone who understands legal procedure or copyright law can answer it better than I can; if so, please feel free to comment.)  But I do think it’s an important one, nevertheless.

Email is probably one of the least secure forms of electronic communication.  It is often said that email should be treated like postcards, where anyone and everyone who touches it can read it.  It’s something I always keep in mind whenever I send email.  I refuse to send critical data (passwords, PHI, financial data, etc.) over email.  If I do have a need to send critical data, I’ll look for a way to do it securely, whether it’s data encryption, secure channels, direct messaging (which may not entirely be secure), or even face-to-face communication.  Data security is a big deal (too big to cover in just a single article), and each news item about data breaches becomes a bigger focus (as of this article, the Facebook data scandal is one of the biggest and most recent; sadly, I do not believe that this will be the biggest, nor the last, such breach).

If someone told me that I had to answer this question (and mind you, this is my opinion; do NOT quote me or state this as fact), the original author (or any data content copyright holder) owns any copyrights.  If I sent a song lyric over email, whomever it was that wrote the lyric would own that copyright, but I would own anything that I wrote (that is, something that came from my head — intellectual property — and not from someone else).  The purpose of a copyright, after all, is to protect intellectual property.  However, given email’s open and unsecure nature, original thoughts posted to an email should probably be considered to be public domain.  (That said, if an email sender cites some data source, has he or she committed a copyright violation?  I won’t take the time to discuss that now, but that might be another topic for another time.)

Despite email’s security concerns, it is still a useful tool, and is pretty much ubiquitous throughout our daily lives.  So long as we keep in mind that it isn’t secure, and we can keep our communication habits in context, it is a technology that will likely not disappear anytime soon.