A few words can make a difference

A couple of weeks ago, the Rensselaer Polytechnic (the RPI student newspaper) published a couple of op-eds in regard to the situation at RPI.  (My friend, Greg Moore, wrote a piece a while back related to this issue.)  In response to the op-eds, I decided to respond with my own letter to the editor.

This morning, a friend posted to my Facebook that my letter, to my surprise, was garnering some attention.  I won’t say that it’s gone viral, but apparently, it’s caught a number of eyes.

I should note that my donations haven’t been much.  I was only a graduate student at Rensselaer, not an undergrad, so the social impact on my life wasn’t quite the same, and other financial obligations have kept me from donating more of my money.  That said, I’ve donated in other ways; I’ve been a hockey season ticket holder for many years (going back to my days as a student), I’ve attended various events (sports, cultural, etc.) on campus, and I’ve donated some of my time to the Institute.

Although my donations have been relatively meager, more importantly, I wanted to spread the word that I was no longer supporting RPI, and exactly why I was discontinuing my support.  How much I was contributing isn’t the issue; the issue is that I am stopping contributing.  For the first time in years, I have no intention of setting foot in the Field House for a hockey game during a season.  I wanted to make clear exactly why.  A large number of alumni have announced that they were withholding donations.  I wanted to add to that chorus.  It wasn’t so much how much I was donating; rather, I wanted to add my voice, and hopefully encourage other students and alumni to take action against an administration that I deem to be oppressive.

One of RPI’s marketing catchphrases is, “why not change the world?”  It looks like I’m doing exactly that with my letter.  Don’t underestimate the power of words.  Indeed, with just a few words, you can change the world.

Advertisements

SQL Saturday #797 — I’m coming to Boston

Happy Monday, all!  </sarcasm>

This is a reminder that I am speaking at SQL Saturday #797, Boston (actually, Burlington, MA) this coming Saturday, Sept. 22!

I will be doing my (still relatively new) presentation about networking, entitled “Networking 101: Building professional relationships” (or, the presentation previously known as “Networking: it isn’t just for breakfast anymore”).  We will discuss why networking is critical for your career, how to go about doing it, and some resources to check out.  You will even have an opportunity to do some networking within the confines of our room.  You might even leave this session with new networking contacts you didn’t previously have!

I’ll see you in Burlington this Saturday!

Comment your damn code!!!

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”
— Martin Fowler

When I was a computer science major in college, I had professors who used to dock points if my code wasn’t documented.  It didn’t matter how well-written my code was, and it didn’t matter how well my code worked.  If I didn’t include comments to describe my code, what my variables were, why I used certain functions and coding techniques, a project that could’ve gotten an A grade instead got a B.

That memory came back to me this evening at our SQL user group meeting this evening.  Our guest speaker was Jen McCown, who gave a presentation called “T-SQL’s Hidden Support Feature.”  (A description of her sessions can be found here, and I found a SQL Saturday link to it here.)  Her presentation talked about a feature included with T-SQL (and just about every language imaginable).  It is guaranteed to improve how people handle, develop, and maintain code, and it costs nearly nothing to implement.

What is this miracle feature, you ask?

Code comments.

Simply commenting code can save developers lots of headaches and development time.  It can provide an explanation of how and why code snippets were used.  It can describe variables, what they’re for, and how they’re utilized.  It can describe program structures that help in debugging and maintenance.  I even remember a comment to a SSC forum post by Jeff Moden who mentioned the return on investment of commenting code.  It also reminded me of Steve Jones’ article about how important it is to comment code.  I believe Jen’s presentation should be required for anyone who writes code.  The benefits for commenting code are endless.

Commenting code is probably one of the simplest and most useful, yet most underutilized, methods of documentation.  I’ve mentioned time and again about how documentation gets no respect in technology, and yet too many developers still refuse to do it.  Jen’s presentation was a reminder of how important it is to document code; in fact, she also mentioned some points that didn’t occur to me.  For example, documents such as Word, Wikis, or Confluence can get lost, misplaced, or buried.  Code comments, however, stay with the code; it cannot get lost or separated from the code.  (There were several other points she mentioned as well, but it’s her presentation, not mine, so I don’t want to take away from it.)

When I was in school, I was docked points when I didn’t comment my code.  Sometimes, I think developers should be docked pay if they don’t do so.  Commenting code is the simplest, yet most effective tools around.  So you want to be a better developer?  Then comment your damn code!

Speaking near Beantown

sqlsaturday-logo

I got an email last night announcing that SQL Saturday #813 Boston — BI Edition has been scheduled for March 30, 2019.  I went ahead and submitted my presentations.

Because the Boston Microsoft office (despite the name, it’s actually in Burlington, MA, about twelve miles northwest of Boston) is a smaller facility, events such as SQL Saturday tend to be smaller; it’s more difficult to be accepted as a speaker, and a wait list for attendees is not uncommon.  Nevertheless, if I am accepted to speak at SQL Saturday #813 (far from a sure thing), that is potentially three trips I’ll make to Burlington within a span of seven months.  I am already scheduled to speak at SQL Saturday #797 on September 22 (a week from this Saturday as I write this) and at a New England SQL User Group meeting on February 13.  SQL Saturday #813 would make it trip #3.

Despite the fact that the Boston area tends to be hostile territory for a Yankee fan like me, I look forward to my upcoming trips.  I’m hoping to make it three trips in seven months.

Hope to see you there!

To paper, or not to paper?

After trying to implement updates to one of my documents.  I realized that I was having problems trying to visualize how to incorporate a number of needed changes.  After staring at my document on the screen for a period of time, I decided to print out my table of contents to better visualize the document structure.  The table of contents serves as a de facto document outline, enabling me to get an idea of the document’s structure.

However, the mere fact that I had to print out the table of contents got me thinking: is paper still relevant in this digital age?

These days, it seems like everything is digitized.  An increasingly number of people are reading books on e-readers and tablets.  Even I, a longtime New York Times reader, stopped buying hardcopy newspapers a long time ago and started maintaining a digital subscription.

That said, there’s something to be said about savoring a good book — a real book, with paper pages to flip, and a dog-eared cover.  Even though I maintain a digital Times subscription, every once in a blue moon, I’ll pick up an actual newspaper and sit myself down in a comfortable chair in a Starbucks, flipping through the pages and getting my fingers dirty with newspaper ink, while enjoying a cup of mocha.

(I’ll also confess to being a little biased, since my wife works in the newspaper industry.)

While viewing documents entirely on a screen seems to be the way of the world these days, I’m finding that there are some instances where there is no substitute for paper.  For starters, I recently wrote that, as a tech writer, I sometimes come across mental blocks in my work.  Viewing a document as a hardcopy, as opposed to on a screen, sometimes helps to break the stalemate.  With paper, I can take whatever individual sheets I need, place them on a table, and skip through whatever I need to edit.  I am able to better visualize document structure and hierarchy so I can better understand where things need to go.  I also have the advantage of being able to pick up a pen and scribble any notes wherever I need them and wherever I please.  Try doing that on a computer screen.

Paper copies could also help alleviate eye strain.  (I am not an expert in this, so for all I know, I might be off-base here.)  I sometimes find it easier to look at material in print than I do on a screen.  I say this, despite the fact that the old tube-style CRT monitors have gone the way of the dinosaur.

By no means am I advocating that we should go out and kill more trees; on the contrary, I am all for taking steps to protect the environment.  All I am saying is that paper is not completely dead.  Although most documentation these days is digitized, I believe that the imminent demise of paper is somewhat exaggerated.

Memories of Pan Am 103

(Photo source: Wikipedia)

There are moments in your life when you remember exactly what you were doing as though it happened yesterday, even if it happened many years ago.  I previously wrote about what I was doing on 9/11.  Likewise, I remember other events, such as the Challenger disaster (I was a freshman at Syracuse having lunch in my dorm dining hall).  In this article, I want to write about another such fateful day.

Yesterday, with only a day to go before Syracuse opens its football season at Western Michigan, I went poking around a couple of websites for more information about the upcoming game.  I went to the Daily Orange‘s website, and in doing so, I stumbled upon this article, which I was not expecting to see.  As soon as I saw it, memories from nearly thirty years ago suddenly came back to me.

On December 21, 1988, I was winding up the fall semester of my senior year at Syracuse University.  I was living in a house that I shared with six other guys only a block off-campus.  It was finals week.  That evening, I was in my room, studying for one of my final exams.  I decided to take a study break and went downstairs to the kitchen to get myself a snack.

As I made my way down the stairs, I saw my housemates in the living room, gathered around the TV.

“What’s going on?” I asked.

“A plane crashed, and there were Syracuse students aboard,” I was told.

I was in shock.  To be honest, I don’t think I got back to studying that night.  I took a seat in the living room with my housemates and was glued to the TV, watching the news for the rest of the night.

The phone started ringing.  A number of band alumni friends (all of us in the house were members of the marching band) had just heard the news, and were calling to ask if any band members were on board.  (Those of you who know about marching band culture understand that band members consider each other to be family.)  At that point, news was just trickling in, and we were not aware of who was on the plane.  I remember hearing that SU students were aboard, but there was no information as to how many of our classmates were affected.  We heard varying numbers: ten, fifteen, nineteen.

I went for a walk around campus the next day.  The campus was eerily deserted, except for a few news trucks parked around the campus to cover the breaking story.  For such a large campus like Syracuse, the entire place felt like a ghost town.  With the nearly empty campus, combined with the cold December air, it was probably the only time I ever felt unnerved walking around the campus.

It turned out that there were thirty-five Syracuse students on Pan Am 103.  Thirty-five of my classmates were gone.  Although I didn’t know any of them, I now feel as close to them as I do any of my friends from college.

Syracuse played a home basketball that night.  As a member of the pep band, I could’ve attended the game, but I opted not to go, since I still had final exams to study for.  I understand that SU got a lot of flak for not canceling the game in light of the tragedy.  They did observe a moment of silence at the beginning of the game.

The marching band did have an opportunity to recognize the tragedy a couple of weeks later.  The Orange football team had played its way to a 9-2 regular season, good enough for a berth in the Hall of Fame (now Outback) Bowl in Tampa, FL.  We wore black ribbons on our uniforms for the game, and observed a moment of silence on the field during our pre-game show.  After the game, I took some White-Out and wrote “PA103” on one half of the ribbon, and “12-21-88” on the other.  I still have that ribbon.

Syracuse University has since paid tribute to the disaster by building a memorial, setting up a scholarship fund, and setting aside a Remembrance Week commemoration each year.  Whenever I’m back on campus, I try to take a moment to spend some time at the memorial as I remember my thirty-five fallen classmates.

Part of my reason for writing this post is so I can go back to that article I found.  At some point, I want to travel to Scotland and take a trip to Lockerbie — a pilgrimage, if you will.  I feel a need to connect with my classmates at the place where they died nearly thirty years ago, as well as pay tribute to the small town that was affected by the tragedy.  The article helped me better understand the town of Lockerbie, which would enable me to better respect the people there who have since moved on from that fateful day.

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.