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.

Technical writing: the Rodney Dangerfield of tech professions

“It exists!” he cried.

“No,” said O’Brien.

He stepped across the room. There was a memory hole in the opposite wall. O’Brien lifted the grating. Unseen, the frail slip of paper was whirling away on the current of warm air; it was vanishing in a flash of flame. O’Brien turned away from the wall.

“Ashes,” he said. “Not even identifiable ashes. Dust. It does not exist. It never existed.”

“But it did exist! It does exist! It exists in memory. I remember it. You remember it.”

“I do not remember it,” said O’Brien.

— Excerpt from 1984 by George Orwell

 

“If it isn’t documented, it didn’t happen.”  — Sohail Sangi

Chores.  Taking out the trash.  Doing the dishes.  Cleaning up the room.  You don’t like doing them.  Neither do I.  Yes, I’ll admit it: I’ll do just about anything to avoid doing them.

Chores exist in the workplace, too (filling out your timesheet, checking your email, and so on).

However, documentation is not a chore.  Why do I say it isn’t?

Because chores at least get done.

A show of hands: how many of you work in a place where everything is well-documented?  Obviously, I can’t see everyone’s hands, but I’d be willing to bet that not a lot of them go up.

I have seen way too many cases where documentation is ignored — often blatantly so.  In my tech writing presentation abstract, I go as far to say that “documentation is one of the most critical, yet most blatantly ignored and disrespected tasks when it comes to technology.”  I go as far as to compare documentation and technical writing as being the “Rodney Dangerfield of technology tasks.”  It gets absolutely no respect at all.

I once told someone that I had technical writing experience.  His response?  “I’m sorry.”

As someone who harps on documentation and communication, this baffles me.  It absolutely bothers me when important things are NOT documented.

Folks, I get it.  I understand that people don’t like to document.  It’s not a sexy task.  Some people believe that watching grass grow and paint dry is more exciting than writing documentation.  People don’t like doing it.

But the fact is, it’s important!!!  Here is a sampling of links I found that describe why documentation is critical.

Occasionally, when I have an idea for a new presentation topic, I’ll post it to the forums on SQLServerCentral for feedback.  When I posted my idea for my tech writing presentation, one of the most profound responses I received was from Jeff Moden, who wrote this response.

So why are documentation and technical writing tasks so universally hated and disrespected?  I don’t have any evidence or data to answer this question (maybe if I decide to pursue a Ph.D, I might focus on this as a point of research), but I can speculate on some possible reasons.

  • “It’s boring.  I just don’t want to do it.”  To my knowledge, nobody has ever said that documentation was fun (well, there might be a few people out there, but I digress).  But there are some ways to make it more fun (more on that below).
  • “I can just remember everything in my head.”  This probably qualifies as being one of the biggest lies of all time.  Can you tell me exactly (and I really mean exactly) what you had for breakfast yesterday, or the day before (or this morning, for that matter)?  Yeah, I didn’t think so.
  • “Nobody documents anymore.  It’s not a big deal.”  See my comment above.  This is another huge lie.  Especially in this day and age where misinformation spreads like wildfire, documentation is critically relevant.
  • “It’s not a priority.”  It absolutely must be a priority.  Documentation needs to be included in project planning.  Make sure that time is budgeted for documentation.  It is that important, people!
  • “I just don’t have the time.”  See my bullet point above.  Make the time, damn it!!!
  • “I’m not a very good writer.”  Not everybody is.  Keep reading for my thoughts on this.

So what are some possible solutions to these issues?  Again, I am speculating on a lot of this, but here are a few things that seem to have worked.

  • Always follow the KISS principle.  Keep it simple, stupid!  This may be one of the oldest rules in the book.  Nobody wants to write a lot of detail, and nobody wants to read it, either.  Sometimes, the less you write, the better.
  • Find a way to make tools easily accessible.  Some of my past jobs included keeping a “scratch notes notebook” (in pre-online days) or incorporating a departmental intranet, Wiki, or team collaboration product (such as Confluence, GitHub, or SharePoint).  Having the tools readily available makes it more likely that they will be used.
  • Establish guidelines.  It seems like people are more likely to document when rules are laid out for them.  It can be something as simple as creating a template for people.  I’ve noticed that when documentation guidelines are established — developing a template or a form for people to use, asking people to write comments when coding, and so on — people tend to stick to them.
  • Document your code.  I had professors in college who used to dock points from my project grades if they weren’t documented or commented, regardless of how good my code was.  If you’re a developer or a programmer, code comments are probably the easiest and most effective ways to document.  Code comments can explain, in just a few lines, what some pieces of code are doing and why some variables are being used.  This allows for easier code updates, troubleshooting, and debugging.
  • Don’t worry about grammar.  As a self-admitted grammar snob, this statement is probably anathema to people like me.  However, writing ability could be a potential roadblock to documentation.  Human beings tend to be self-aware about their mistakes, which prevents them from doing their best, and documentation is no exception.  If you are self-aware about how you write, go ahead and write without grammatical restrictions.  So long as ideas are conveyed and understood, it should not be a roadblock.  If your document needs to go to customers, have an editor (or someone who knows what they’re doing) review it and make it look pretty later.
  • Find a way to make it fun.  Even my own attention span is reduced and my eyes glaze over after spending a couple of hours working on documentation, especially text.  However, I’ve noticed that working on some types of documentation — especially anything that involves illustrations, visualization, and UX/UI — tends to keep my attention much more than writing instructions or text.  Humans are visual animals, and we are more receptive to visual cues.  Creating (and consuming) illustrations tends to be easier (and more fun) that consuming text
  • Be a subject matter expert (SME).  Maybe the answer is that you don’t have to write at all.  If you really don’t like to write, then make yourself available to someone who does, and let that person worry about the documentation heavy lifting.  Sharing your expertise contributes to documentation.

This is by no means a comprehensive list (as I stated earlier, I’m speculating on a lot of this).  If you have anything more to add, by all means, please do so in the comments.  Your ideas might just make their way into a future presentation or ‘blog article.

I absolutely believe that ignoring documentation is a recipe for disaster — maybe not immediately, but it will happen somewhere down the line.  These issues (and maybe some others I haven’t thought about) must be addressed.  Documentation can pull your butt out of the fire and save it.  The lack of it can guarantee that you go down in flames.