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.

Advertisements

One thought on “Setting a good example

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.