Don’t forget to edit your system messages

One of my current work projects is a administrative guide for our application. After a recent status meeting, one of the developers sent me a list of validation error messages that might appear during data imports. I was asked to make sure the validation messages were included with the documentation.

While going through the validation messages, I noticed that they were filled with grammatical, capitalization, and spelling errors. I asked the developer if he wanted me to edit the messages, to which he responded, “yes, please!”

People don’t think about checking output messages for correctness during application development. It is often a part of applications that is overlooked. For what it’s worth, I, myself, didn’t even think about it until I was asked about these validations. Nevertheless, reviewing and editing output messages is probably a pretty good idea.

For one thing, and I’ve stated this before, good writing reflects upon your organization. Well-written documentation can be indicative that a company cares enough about their product and their reputation that they make the effort to produce quality documentation as well. Well-written system messages indicate that you care enough to address even the little things.

Well-written error messages can also ensure better application usage and UX. A good output message can direct an end user to properly use the application or make any needed adjustments. Messages that are confusing, misleading, badly-written, or ambiguous could potentially result in things like application misuse, corrupted data, accidental security breaches, and user frustration.

Ensure your application development review and testing also includes a review of your system messages. It may be a small thing, but it could potentially address a number of issues. As someone once said, it’s the little things that count.

Dashboard design = UX/UI

This is another article that was borne from my experience at SQL Saturday #814.

When I went to my room to get ready for my first presentation of the day, I walked in on the tail end of Kevin Feasel‘s presentation about dashboard visualization techniques.  I caught about the last ten minutes of his session.

And from those ten minutes, I regret not having sat through his session.

Kevin’s presentation focused on dashboard layout and design.  In the short time in which I saw his last few slides, he showed off his impressions of a badly-designed dashboard, and talked about what not to do.  In other words, he was talking about UX/UI — a subject near and dear to my heart.  It reminded me of the article I wrote about poor design a while back.

I wish I had read through the presentation schedule more clearly.  That was definitely a presentation that I would have liked to have seen.  In my defense, during that time slot, I was sitting in the speaker’s room getting ready to do my own presentation.  But I would have gladly spent that time sitting through a presentation that interests me — and this one definitely qualified.

I’ve attended a number of SQL Saturdays, and I’ve crossed paths with Kevin a few times.  If we’re both attending a SQL Saturday, and Kevin is doing this presentation again, I’ll make sure that I’m there.  I don’t want to miss it a second time.

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!

Why design matters

“A user interface is like a joke. If you have to explain it, it’s not that good.”
— unknown

There are two elevators in the building where I work, including one that doubles as a freight elevator — it has front and back doors for access.  This particular elevator has a bank of buttons shown in the photo below.  The buttons for the rear door are denoted by the “R” next to the floor number.

elevator_buttons

Here’s why these buttons frustrate me.  Quickly, tell me which open and close door buttons work for the front and rear doors!  Yeah, I can’t tell, either!  You would think that the upper buttons control the front and the lower ones control the rear, but you can’t discern that from the way it’s laid out (and I’ve found that it isn’t necessarily the case).  I have had multiple occasions where I’ve tried to hold the door open for someone rushing to catch the elevator, and ended up hitting the wrong button.

Had these buttons been properly laid out, the open and close door buttons would both been placed under each respective door button column — i.e. the open and close door buttons that control the rear door should have been placed under the buttons marked “R,” which would clearly indicate that those buttons are used for the rear door.  That would make sense, wouldn’t it?

Raise your hand if you’ve ever been frustrated by a product simply because the user interface was poorly designed.  I would expect every hand in the room to be up.

Don Norman, an academic researcher considered to be an expert in usability design, talks about this phenomenon in his book, The Design of Everyday Things (disclosure: at the time of this article, I have not read this book — yet).  One very common example involves doors.  How many times have you come across a door with a handle, leading you to think you need to pull it to open the door?  Yet when you try it, it turns out that you need to push, not pull it, to open.  It’s extremely frustrating, and it happens more often than you think — so often, in fact, that it even has a name: a Norman door.

If you don’t think good design isn’t a big deal, there have been documented cases where poorly designed interfaces resulted in a significant loss of life.  I did a Google search for “disasters resulting from bad design,” and the results were startling.

This subject is of particular interest to me, speaking as someone whose job revolves extensively around technical communication, technical writing, and front-end development.  In my line of work, design and layout are a big deal.  I have seen many examples on the job of horrible documentation and bad interfaces — and poor design was a major factor.  I mentioned in an earlier article that I came across illustrations in a company document that were completely useless.  Pictures may be worth a thousand words, but if they’re not properly used — and yes, there is a wrong way to use them — they can be worth exactly zero words.  Likewise, one of my current projects is working on how to make an internal corporate social network work for my department.  I’ve discovered that I have a love/hate relationship with it; while I have no problem with the concept, the execution leaves a lot to be desired.  One of the most basic questions I have with this system which it fails to answer — and which should only be answered by the interface design without having to look up instructions — is, “where am I supposed to begin?!?”

Interfaces exist in just about every facet of our lives, including, but not limited to, application front-ends.  Good sensible design must be involved in creating them.  More often than not, they’re just “thrown together” without any thought as to how they should be laid out and how they are to be used.  The consequences of poor design abound.  In the best of cases, such as with Norman doors, they are just annoying.  But in the worst cases, they can have disastrous and fatal results.

My introduction to Docker

With my (still-relatively) new job comes an introduction to new (to me) technology. In this case, the technology in question is Docker.

For those of you unfamiliar with Docker (like me), it is, in a nutshell, a tool for deploying and running an application within a container. It is an improvement over VM (virtual machine) in that it runs at the operating system, rather than the hardware, level, resulting in less overhead and a more efficient environment.

As part of my indoctrination into Docker, I looked up some resources to help me get started.  I found this entry that seems to be very helpful.  I’m sure I’ll find some others as well.  I’ll post them as I go along.  I also installed Docker on my work laptop and have been playing with it.  At the moment, I am far from an expert on Docker (in fact, I’m not even close), but I feel like I’m starting to get the hang of how it works.  Hopefully, I’ll be productive with it before long.

I also noticed that, in the schedule for our upcoming SQL Saturday, one of the sessions focuses on Docker.  I intend to attend that session.  At this point, any resource that helps me to learn this technology is definitely of interest.

Does anyone else have any suggested resources for helping me (and others) learn Docker?  Feel free to comment below!

Scary Deployments

My friend Steve Jones ‘blogged this, and this spoke to me enough that I thought it was worth a re-blog.

Voice of the DBA

I was listening to a web developer talk about some fundamental changes in a web platform. In this case, an older system was being replaced completely with a new one, and as one of the reasons, the developer showed some typos that had existed on the old site for years and hadn’t been fixed. The reason? This quote:

“Very few people understand how the entire system works that are still in the building … The thought of deploying [changes] brought people to tears.”

That can’t happen. Ever. We can’t be afraid to touch systems. When this happens we get paralyzed, and we don’t do good work. Or we’re not a good fit for a project. Or perhaps, we’ve got a bad attitude.

I’ve worked in a few companies where developers were afraid to touch a system. It’s amazing how quickly this attitude becomes contagious, even scaring management from considering change…

View original post 148 more words