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.

Advertisements

A user group is a good place to start

“The journey of a thousand miles begins with one step.”
— Lao Tzu

Earlier this week, a friend at my CrossFit gym (and who has become more interested SQL Saturday and my SQL user group) asked me if I thought a talk about Excel would make a good topic for SQL Saturday.  I said, why not?  If it’s a talk that data professionals would find interesting, then it would make for a good talk.  I encouraged him to attend our next user group meeting and talk to our group chair about scheduling a presentation.

I’ve written before about how local user groups are a wonderful thing.  It is a great place to network and socialize.  It is a free educational source.  And if you’re looking to get started in a public speaking forum, your local user group is a great place to start.

I attended my first SQL Saturday in 2010, and I knew from the very start that I wanted to be involved in it.  Our local SQL user group was borne from that trip (Dan Bowlin — one of our co-founders — and I met on the train going to that event).  I came up with a presentation idea that I developed and “tried out” at a user group meeting.  I submitted that presentation to a few SQL Saturdays.

That user group presentation was in 2015.  I’ve been speaking at SQL Saturdays ever since then.

If you’re interested in getting into speaking, if you want to meet new people who share your interests, or even if you just want to learn something new, go find a local user group that matches your interests and check it out.  You’ll find it to be a great place to kickstart your endeavors, and it could lead to bigger things.

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.