A picture is worth (writing) a thousand words

On a recent project in which I was documenting an application, I found myself hitting yet another case of technical writer’s block. I sat in front of the screen, staring at the application — sometimes, for hours — and came to the realization that all I was doing was blankly staring at the screen. I tried different techniques to stir up ideas as to how to tackle writing the documentation, but no matter what I tried, the words just wouldn’t come. Even just trying to figure out a document structure — never mind actually trying to describe the application — was proving to be elusive.

It was at that point where I decided to give up on trying to write a description of the application functions and turned my attention to grabbing screen captures. I went through the application’s menu structure, built a document heading hierarchy based on it, and started working on the application images I’d just captured. I took the time to clean up the images, including altering them to eliminate any client or user data (replacing them with “dummy” data), and formatting them for my document. Once I was satisfied with the result, I inserted it into the document, proceeded to the next screen capture, and repeated the process.

A funny thing happened during this process. First, I found that my document was expanding in content. Granted, it was mostly graphics, but it was, nonetheless, content. Second, I’m finding it easier to come up with ideas for descriptions and text content. Third, I’m no longer blankly staring at my screen; I’m finding that I’m actually productive. Finally, I’m finding myself having fun with the process!

This is not the first time that I’ve performed this process while writing a document. Indeed, I’ve often worked on documents in which I found myself in a writing rut, shifted gears to work on graphics, and discovered the spark that I needed to write the text.

It’s an age-old saying that “a picture is worth a thousand words.” Most often, this phrase is geared toward the perspective of the reader. However, what is not as appreciated is that this cliché is applicable to the document developer as well. If ever you find yourself in a writing rut, try working on the graphics. It might just be enough to spark ideas and get you out of the rut.

First drafts are ugly

“The secret to life is editing. Write that down. Okay, now cross it out.”

William Safire, 1990 Syracuse University commencement speech

“No thinking – that comes later. You must write your first draft with your heart. You rewrite with your head. The first key to writing is… to write, not to think!”

William Forrester (Sean Connery), Finding Forrester

“Just do it.”

Nike

I will confess that this article is a reminder to myself as much as anything else.

Raise your hand if you’re a writer, and whatever it is you’re writing has to be perfect the first time around. Yeah, me too.

How many times have you tried writing something, but in doing so, you hit a wall (a.k.a. writer’s block) because you don’t quite know how to put something in writing? Or how often have you written a first draft, only to take a second look at it a second time and say, “what a piece of s**t!”

(And speaking as someone with application development experience, this happens with writing code, too. Don’t think that this is limited to just documentation. This is yet another example of how technical writing and application development are related.)

Someone (I don’t know whom) once said, “one of the stupidest phrases ever coined is, ‘get it right the first time.’ It’s almost never done right the first time!” In all likelihood, you need to go through several iterations — review, editing, rewriting, etc. — before a draft is ready for public consumption. It’s called a “draft” for a reason.

The fact is, nobody has to see what you write the first time around. If you’re trying to get started on a document, just write what’s on your mind, and worry about making it look nice later.

Coming up with presentation ideas

As a followup to yesterday’s article, I thought it might be fitting to talk about presentation ideas.

Despite the fact that I speak regularly at SQL Saturday, none of my presentations (up to this point) have anything to do with SQL Server or even anything data-related. My topics revolve mostly around documentation and communication. So how do I go about coming up with presentation topics?

To answer this, I suppose I should go back to the beginning, and (re-)tell the tale as to how I got involved.

Back when I was primarily a SQL Saturday attendee, I knew I wanted to get involved. The question was, how? At the time, I looked around at the people attending the event, and I said to myself, “these people probably know more about SQL Server than I do. What can I present that these people would find interesting?”

In the early days of our user group (I was one of the original co-founders and members), we sought out speakers to present. I thought about data-related topics. I even took a turn one meeting where we were encouraged to bring up SQL-related issues as discussion topics. But when it came to ideas for data-related topics, I kept coming up empty.

I thought about a time at one of my jobs where I became an accidental customer service analyst. As a developer, I was not allowed to speak with end-users, but one day, I received a phone call from a user. It turned out that he had gotten my number from someone who was not supposed to give out my number. I was able to walk him through and satisfactorily resolve his issue. In fact, I did such a good job with it that, from that point forward, I became one of the few developer/analysts who was allowed to talk to customers. It made me realize that I had a knack of being able to discuss technology with end-users without being condescending to them.

During one user group meeting, I jotted some notes down. By the end of the meeting, I had come up with enough material for a presentation. I ran my idea past my fellow user group attendees, all of whom said, “that would make a great presentation!”

I worked on the presentation and presented it at a user group meeting.

Four years later, I will be giving that same presentation at PASS Summit! I’ve come a long way!

While that ended up being a good presentation, I’ve tried not to rest on my laurels. I still try to come up with new presentation ideas. I’ve come up with several since then, and I’m still trying to come up with more.

When I think about presentation ideas, I generally keep these thoughts in mind.

  • Is it a topic that attendees will find interesting?
  • Is it unique?
  • Is it something about which I’m knowledgeable, and I feel comfortable talking about?
  • Is it something I can present within an hour? And do I need to cut it back to an hour, or do I need to fill it in to an hour?

I still remember a piece of advice that Chris Bell, a DBA and fellow SQL Saturday speaker, once told me: “an expert is someone who knows something that you don’t.” That was profound advice, and I’ve never forgotten it. So far, it’s served me well in my speaking endeavors.

So if you struggle to come up with presentation ideas (like I do!), hopefully this will help you get the ball rolling. I look forward to seeing your presentation soon!

Collaboration, cooperation, and competition

This is another article based on stuff that I picked up from SQL Saturday #814.  This time, I’ll talk about Matt Cushing’s presentation about networking.

Whenever I’m speaking at a SQL Saturday, I always make it a point to attend sessions that are similar to mine.  At #814, I met Matt Cushing, who was doing a session on networking.  In fact, our presentations had very similar titles; they both started with “Networking 101.”  That very much caught my attention, and once I finished my own (my presentation was in the time slot immediately before his), I went to his room to catch his presentation.

A big reason why I attend presentations similar to mine is that everyone is different, and will therefore present differently.  Other people will have different perspectives of the same topic.  I want to see these other perspectives.  They might have ideas that will help me enhance my own presentations.  Every time I attend a session in which the topic is relevant to my own, I come across something that either never occurred to me, presents an idea in a different way, or reinforces concepts in my own presentations.  These are important, and they help me make my presentations even better.

Matt gave a great presentation!  I found his own self-assessment on his ‘blog.  I found out that it was Matt’s first-ever SQL Saturday presentation.  I had no idea!  He did a great job with it.  (Matt, if you’re reading this, well done!)  I don’t remember all the points from his session (I’ll need to download his presentation slides), but one takeaway was that “competition is good, cooperation is better.”  (This thought inspired the name of this article you’re reading now.)

This concept of cooperation is applicable to countless situations, and SQL Saturday presentations are no exception.  Many presenters refer to other speakers or other presentations; even in my own presentations, I’ll encourage audience members to go check out other presentations that are similar to my own topic.  (Ed. note: I need to make sure I add a reference to Matt’s presentation in my own slides!)  Matt and I joked that we should encourage SQL Saturday organizers to schedule our sessions back-to-back; we even went as far as to say that we should do a joint presentation.  (Matt, I’m game if you are!)

In a way, Matt is a competitor in that we did similar presentations.  However, we were both able to learn and feed off each other, which enables us both to improve; it’s a win-win for both of us.  Competition is a healthy thing; it drives us to do our best.  But when you cooperate with your competition, there’s no telling what you can accomplish.

Write it down, stupid!

Years ago, I went to visit my brother at his place in Queens.  I remember sneaking a peek into his home office.  As a reminder to himself, he’d stuck a label on his computer monitor with four words, in all caps: WRITE IT DOWN, STUPID!!!

This is pretty much my own mantra as well.  Any time I have an important task that needs to be addressed, I’ll do one of two things: either 1) do it right away, or 2) make a note to take care of it later.  I know myself well-enough that if I don’t do either, the task will either not get done or an important deadline or opportunity will be missed.

There is a reason why technical communication is such a passion of mine.  I’ve seen countless examples in the professional world where things are not documented.  I’ve heard a variety of excuses of why they’re not documented: “Oh it’s not that difficult to remember.”  “It’s intuitively obvious.”  “It cannot be missed.”  “I won’t forget that one.”  “I don’t have to bother with it now.  I’ll get to it later.”  And so on.  And so on.  And so on.

It’s not just professional communication, either.  When was the last time that you came up with a great idea that could change the world?  Did you write it down?  If you didn’t, do you even remember what it was?

I’ve long been a believer that open and honest communication is a game-changer.  Indeed, I’ve often told people that “90% of the world’s problems can be solved through communication.”  (Before you ask, no, I don’t have any hard evidence or statistics to back that up, but it is something I believe.)

Writing things down is a core part of communication.  When you write things down, you aren’t just communicating with other people; you’re communicating with yourself — your future self — as well.

Technical writer’s block

“What no wife of a writer can ever understand is that a writer is working when he’s staring out of the window.”
— Burton Rascoe

“Waiting for the break of day; searching for something to say; flashing lights against the sky; giving up, I close my eyes…”
— Chicago, “25 or 6 to 4”

Those of you who write creatively — whether it’s a book, an article, music, etc. — have all experienced writer’s block.  Even if you don’t write, maybe you’ve experienced it in some form.  Maybe you were assigned a writing project in school.  Maybe you’re trying to come up with ideas for a party or how to celebrate a co-worker’s special occasion.  It even comes up when my wife and I discuss what to do about dinner (“What do you want?”  “I don’t know!  What do you want?”).  No matter what form it takes, the moment when your brain fails to come up with any ideas (sometimes called a “brain cramp”) happens to all of us at some time or another and more often than we’ll admit.  As much as I’d like to post a ‘blog article each day, there’s a reason why I don’t.  A lot of it is because I don’t necessarily write articles professionally and I don’t always have the time to do it, but an equal part of the reason is not being able to think of things to write about.

For this article, I’d like to talk about technical writer’s block — yes, there is such a thing, and it happens more often than you think.  (I don’t know if that’s a widespread term; for all I know, I might have just coined a new phrase.)  However, it differs from other forms of writer’s block in that a technical writer already has a subject about which he or she is writing.  In this case, it’s not a matter of what you’re writing about; it’s more a question of how to write about it.  I can’t tell you how many times I’ve stared at a computer screen for (at least) twenty minutes, only to realize that I spent those twenty minutes just blankly staring at the screen.

Those of you who are technical writers, let’s see a show of hands: how many of you have been given, say, a step-by-step instruction to write about, but have agonized about how to put it together?  Should you list them as numbered instructions?  Should you keep it to simple bullet points?  Is it better to put items into a table and write out definitions for the terms?  People who know nothing about technical writing don’t understand the struggle; they think it’s just a matter of throwing it together and making numbered points from them.  What they don’t realize is that it is not that simple.

For one thing, writing instructions isn’t that much different than writing code.  Both involve logic.  But let’s say you have an instruction to “push the red button” but only if you performed another step or are faced with a specific circumstance.  In structured programming, this would probably take the form of an IF-THEN or CASE statement.  But when you’re writing a document, situational instructions aren’t as clear cut.  There is no standardized method for writing an if-then statement in a step-by-step document.  I’ve seen this situation addressed in different ways; in one job where I was employed as a full-time technical writer, the group include a style with their template that included a small table for these situations: do this for one situation, do that for another.  I’ve seen others where a step is accompanied by a note: “this only applies to (whatever).”  Since there is no standard way to address this, it likely makes writing instructions more, not less, difficult than writing code.

Your audience likely plays a role.  I’ve espoused time and again that you need to know the audience for which you’re writing.  In my first successful technical writing project, I made sure that I put myself in the reader’s shoes, empathizing with the reader.  “How do I write this so I can see what I need to do?”  That strategy made things very clear, and I was able to write a good document.  Unfortunately, tech writers don’t always have this luxury; sometimes, either the type of audience is unclear, or the writer is writing for multiple audiences.  If you know your audience, it gives you an idea as to how to structure and write your document.

As I wrote earlier, design matters.  Of all my experiences with technical writer’s block, this is probably the one with which I struggle the most.  How should things be laid out that would most help the reader?  Where should things be placed so that they best direct an end user?  A document’s design often makes or breaks a successful document.

I just wrote about some of the issues I face.  How to resolve them is not as clear cut, and I don’t have as many answers as to how to address them (that might be worth its own article).  Here are a few ways that I’ve dealt with technical writer’s block.

  • Ask questions.  Clarification helps answer some of the issues with which I have to deal.
  • Get help.  Another set of eyes can sometimes break the impasse.
  • Work on something else.  Working on another task can sometimes spur ideas.
  • Walk away.  Sometimes, you just need to take a break.

I’m sure there are others ways as well that haven’t occurred to me.  How do you deal with technical writer’s block?  Feel free to respond in the comments.

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.