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.

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!

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.

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