Don’t keep an idea to yourself

My friend Greg Moore recently commented on a Facebook post regarding our upcoming SQL Saturday (tomorrow!) in which he credited me for my idea about a forum about women in technology.  The idea had occurred to me when I saw that Rochester SQL Saturday was doing such a forum, and I suggested that we should do one as well.  To be honest, I’d forgotten that I’d made the suggestion until I saw Greg’s comment earlier this week.

It just goes to show that you never know where an idea might lead.  I made a simple suggestion about an idea I’d seen about a forum discussion.  Tomorrow, it’s going to become reality.

For whatever reason, it made me think about the following meme.

Image result for sharknado meme

So the moral of the story: if you have an idea, don’t keep it to yourself.  You never know where it might lead.

Advertisements

The document development life cycle

A recent work request reminded me of production life cycles.  I got an email regarding a user guide for an application that I had written earlier this year.  She said she was looking for something similar.  She asked me how long it would take.  I told her that I would need to look at the application, but I also said there were a number of things to consider, including how much access I could have to the application so I could test and document it, who would be available to answer any questions I had, who would be able to test and review the document, the document format, and so on.  (On hindsight, I also realized that I’d forgotten to ask a very important question: who is the audience?)

The conversation reminded me about the importance of the document development life cycle.  In an earlier article, I talked about a number of issues that frustrate people who understand technical communication and documentation.  This is another frustration that is poorly understood and widely ignored.

I’ve had the privilege of having worked in both software development and professional document development environments.  Many people fail to understand that there is no difference in the production process between the two environments.  To put it another way, the development life cycle between the two is no different!!!  The software development life cycle (SDLC) is widely known and an industry-standard term.  But if you’re not a technical writer or communicator, when was the last time you heard any mention of a document development life cycle?  For that matter, are you even aware that such a thing exists?

It seems to me that most people aren’t.  How many of you have been frustrated when you’re given a documentation project, whether it’s an application, a process, or a product, and been told that it needs to be finished in a couple of days (or even a couple of hours)?  This is completely disrespectful to technical writers, and it upsets me to no end.

An example of a software development life cycle
(source: SoftwareTestingMaterial.com)

Like software, producing good documentation follows a life cycle.  Here’s a sampling of what takes place when developing a document.  Document requirements must be defined: what is being documented, what is the scope, and so on.  And let’s also not forget what may very well be the most important requirement: who is the target audience?  The document must be designed and written.  This involves organization, layout, and design.  Writing it is no small task; I’ve written before about how hard it is to interpret ideas that come from a subject matter expert (SME).  Once a document draft is written, it needs to be reviewed (“tested”) by an SME for accuracy; are the ideas conveyed in the document correct?  Adjustments to the document will likely need to be made, and it will need to go back to the technical writer for editing and updates.  Document format needs to be considered; will it be deployed as a PDF document, or will it be stored and maintained in an online format, such as a Wiki, Sharepoint, or Confluence?  Speaking of maintenance, bear in mind that if the application or process is changed, the document will likely need to be changed as well.

Documentation is a critical, yet overlooked and disrespected, profession in technology.  A technical writer cannot be expected to produce a quality document in mere hours.  As with all quality products, documentation also follows a life cycle.  Whenever the document life cycle is properly followed, the result is a quality document, which, in turn, results in satisfied customers and a positive reputation for your organization.

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.

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.