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!

Advertisements

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.

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.

Agnostic document references

Many of you who are technical writers — or data professionals — understand how important it is to not expose real data.  There is a huge emphasis on data security, as there should be.  But a lot of people never think about smaller pieces of data within a document — something as simple as, say, an email address.  In a lot of documentation I write, I make it a point to make much of it as anonymous and agnostic as possible.  There are a number of reasons for this, as I outline below.

I’ll start with a point of emphasis that I make in documentation time and again: know your audience.  Earlier this year, I was responsible for writing a user guide for an application that was to be used by multiple clients.  When I first started working on the document, the application was only being used by one client.  The application — and the document — contained many references to that one client.  In order to update the application to serve multiple clients, all references to the one client had to be removed, not just in the application itself but also in the documentation.  If a document is to be used by multiple audiences, specific client references should be made generic.

Likewise, I’ve accessed applications that display my name on the screen: “Welcome, Ray Kim,” for example.  If I screen-capture that image, I often alter the image so that my name is removed.  I don’t know about you, but I wouldn’t want to be contacted incessantly about an application that I probably know little about.

Another reason is data security, which becomes a larger issue by the day.  Sensitive corporate data risks being exposed within documentation.  For example, for my screen captures and illustrations, I request a “dummy” account that displays “bogus” corporate data for document illustration purposes.  I’ve gotten into the habit where I request this for every document I write.  Corporate data is sensitive; indeed, there is an increasing awareness of keeping such data private (the European Union’s GDPR and laws such as HIPAA and various other data protection laws come to mind).  Live data should never be used in documentation (unless authorized by the client in question); you can never tell what can be revealed in that data.

Here’s another reason I have for keeping documentation generic.  Let’s say, for example, an instruction for additional help directs you to “contact john.smith@yourcompany.com” in your document.  However, there’s one problem: John Smith no longer works for the company.  The correct contact is john.public@yourcompany.com.  But nobody made you aware of this change, nor is anyone aware that this contact is in the documentation.  And who is to say that John Public won’t leave the company or change roles in the next couple of weeks?  Additionally, listing a specific person runs the risk of that person getting spammed by peope who decide to use the contact for reasons other than the one listed in the document.  These risks come up any time a document references a specific person.  A better approach is to reference something more generic — say, a generic mailbox (e.g. HelpDesk@yourcompany.com) or a departmental site.

Here’s another argument for using generic references: how often does the document need to be updated?  Let’s say, for example, you write a document that references “Acme Corporation.”  Over the course of time, “Acme Corporation” changes — perhaps the company is bought or merged, the name changes, and so on.  How often do you need to go through your document looking for “Acme Corporation” and all its variations (shortened to “Acme,” abbreviated as “AC,” misspellings, etc.)?  And suppose your document is hundreds of pages long, with company references interspersed all throughout the document?  Making those edits does not make for a good working day.

Documentation runs the risk of exposing large amounts of data.  For data security, privacy, or even simple editing reasons (and maybe a bunch of others that I haven’t thought about yet), unless there’s a specific reason for not doing so, illustrations, examples, and references should often be made generic.  It’s a simple but critical step that can make your job better as a technical writer, and save your organization from a number of headaches — possibly ranging from complaints from audience members to a lawsuit.

It was the best of times, it was the worst of times

Steve Jones recently asked: what were your best days at work, and what was your worst?  He also issued a challenge to write about our typical days at work.  In terms of writing about a typical workday, I have the first of four (per Steve’s challenge instructions) draft articles warming up in the bullpen; hopefully, I’ll crank that one out sometime within the next week or so.  But in the meantime, for this article, I want to take a moment to address the best and worst days.

In terms of the worst day, I don’t think there is any contest.  I think it’s pretty safe to say that 9/11 was my worst day at work.  (For the benefit of those of you who don’t feel like clicking my article link, I worked for a company that had an office in the World Trade Center — when 9/11 happened.)

In terms of the best days, however, that requires a little more thought.  It’s not that I haven’t had any great days — that isn’t true — it’s just that there are a number of them, and having been a working professional for (cough! cough!!!) years, trying to pick out a few that stand out over the years is difficult for me to do.  So what I’ll do is pick out a few project victories that I’ve had over the course of my career.  Granted, I’m picking these from the top of my head, and there very well might be others that were more significant that I’m not remembering right now, but for purposes of this exercise, I’ll write about some projects with which I was involved and take a measure of pride.

I’ll start with a project related to the worst day that I mentioned above.  One of my tasks was to maintain an inventory of the servers in our data centers.  For a long time, this was a tediously manual task.  I went through our data centers with a clipboard, checking to see what servers were in each rack, noting any changes and adding new servers and racks that I found.  I drew a map of each room in Visio, even going as far as to count the floor tiles so that I could draw them to scale.  I populated the maps with boxes representing server racks and came up with a naming scheme directly tied into a row-and-column location scheme, making it possible to identify and label each rack so they’d be easy to find.  Included with the maps was a listing of servers within each rack.  I maintained the Visio file on my PC, making sure it was backed up to a departmental file server, and keeping hardcopies in each server room as a reference for various IT workers.

Because this was a manual process, the maps were never completely accurate — I have no doubt that new servers were continually added in-between map updates — and it was a tedious process.  All the while, I kept thinking, “there has to be a better way to do this.”  Sure enough, I found one!

I discovered that all our servers included a product called Insight Manager.  Among other things, it included the ability to collect server BIOS information and store it in a format suitable for importing into a database such as SQL Server.  Using the Insight Manager data structure as a template, I set up a SQL Server database on one of our departmental servers and created a system that enabled it to import data from any server on demand through Insight Manager.  I now had a central database with server data that could be updated at any given time!

Of course, data isn’t information unless it can be interpreted and understood, so the next step was to create an interface for it.  I was responsible for maintaining a departmental intranet site; although it was an internal intranet, I treated it as though it was a full-blown web site.  I created a web site to display the server data stored in my back-end.  I took my Visio server room maps and created image files from them.  From the image files, I created image maps that enabled a user to click a server rack on the map, drilling down to a list of servers in that rack.  Clicking on a server displayed data for that server — serial numbers, IP addresses, applications, and so on.

My server inventory system, which I previously had to update manually, was now automated!

This project was a major milestone for my career.  It was my first significant foray into SQL Server.  (At that time, I hadn’t yet learned about data normalization; had I known about it, I could’ve made the back-end even better.)  It gave me some experience with image maps, HTML, and classic ASP (the technology used on that intranet server at that time).  Most of all, it was my first taste of what it was like to be a web applications developer.

Memories of this project also reminded me of another good day I had on the job.  One particular day, I traveled to remote offices in Yorktown Heights and Middletown to survey their data centers for the server inventory system that I just described.  I hopped into my truck (I owned a small Toyota pickup truck at the time) and drove to Yorktown.  It was a gorgeous picture-perfect day; the sun was out and it was comfortably warm with low humidity.  It was comfortable enough that I left the air conditioner turned off and drove the entire trip with my windows rolled all the way down.  It was the kind of day where I wished I owned a convertible!  My route between the Yorktown and Middletown offices took me through the Bear Mountain area, including traversing the Hudson River over the Bear Mountain Bridge.  If you’ve never driven through that area of New York State, it is an absolutely picturesque and beautiful drive.  The entire trip was so fun and relaxing that it did not feel like a business trip at all; I actually felt as though I was on a vacation!

Finally, I want to talk about one last project in which I had a hand.  In one of my first jobs out of college (my second job out of school, actually), I was responsible for supporting my company’s document imaging system at a client site (a client that eventually ended up hiring me directly).  One of the system’s components was a WORM optical platter jukebox that was in constant use and occasionally needed operations maintenance, which ranged from simple tasks such as inserting an optical platter to complex ones such as restarting it when it locked up.  The device had to be operational 24/7, even at hours when we were not in the office.

I was tasked with putting together a small set of instructions — nothing big, just a few pages — that explained how to perform these tasks, including the correct way to insert a platter, what to do when (unfortunately, not if) the machine stopped working, and so on.  It needed to be written in such a way that the night maintenance staff could maintain the device.  So I sat down in front of my PC with a blank MS Word file and said to myself, “if I was a member of the night staff, what would I want to read that would enable me to perform these tasks?”

I had intended for the document to be a simple three to four page quick reference.  As I wrote and came up with more ideas that would help the readers who would be using it (including the innovative — for me — use of illustrations), the document kept getting bigger and bigger.  I don’t remember how big it eventually became, but I think it was somewhere in the ballpark of thirty pages.  I had absolutely zero technical writing experience at the time; I wrote the document completely by instinct.  I didn’t really know what I was doing; I just did things (illustrations, headers, subject organizations, etc.) that made sense to me.

The final product was a huge success — so much so, in fact, that management developed a training program based around this document.

A couple of years later, I discovered that nearby Rensselaer Polytechnic Institute had a Masters degree program in technical communication (note: I am not entirely sure if the program still exists).  I had been interested in pursuing a graduate degree, and I thought the program sounded interesting, so I decided to apply.  During my application interview with the faculty, I brought along a copy of that operational jukebox document I’d written.  I explained that I’d written the document completely by instinct and with no knowledge or experience in technical writing whatsoever.  The faculty seemed to be impressed with my effort on that project.

I was accepted into the program.  I now have an MS from RPI hanging on my home office wall and listed on my resume.

This article ended up being a lot longer than I expected.  Looking back on this exercise that Steve assigned, I suppose my good days at work were more significant than I thought.  These projects were major events that ended up shaping this professional career.  I suppose the moral of the story is not to underestimate job achievements.  You never know where they might lead!

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.

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.