This week, I was introduced to a new (to me) methodology called the C4 model. Now, in this context, C4 does not refer to the high explosive. In this case, C4 refers to a development methodology. Mostly, it refers to software development, but it has other applications as well, and that includes document development.
As part of my indoctrination into this methodology, I was provided this link. So far, it looks like an interesting read. I’m still reading about it, but here’s my understanding of the methodology thus far.
First of all, C4 stands for context, containers, components, and code. Think of it as looking at something at four different levels, from the top level (context) that shows the big picture, all the way down to the most minute detail (code).
The top level (context) refers to the big picture. Using maps as an example, here is a map of the United States — for purposes of this example, the big picture. You’ll notice that I drew a black box around New York State, which indicates the next level to which I will zoom.
If we want to drill down to the next level (container), a state would be the next logical level. So for the next map, I’m drilling down to my home state of New York. Again, I’m drawing a black box around the area to where I will drill down next.
A city or region is the next logical step (component). Let’s drill down even further, this time to my home city of Troy. Again, I’m drawing a black box around the next level to which I will zoom.
The bottom level of this methodology (code) shows the minute detail. For personal privacy reasons, I’m not using my home location, so instead, I’ll use one of my favorite establishments: Brown’s.
You’ll notice that I did not draw a black box in the last illustration; this is because we are at the lowest level in this model. I suppose if I really wanted to get granular, I could drill down into building floor plans, but for the purposes of this example, I think the point is made.
From how I understand it, the C4 methodology appears to be used for diagramming and documentation. It addresses a shortcoming in many technical diagrams in which they can be confusing and difficult to follow. C4 addresses this by showing how components relate to the big picture.
While I haven’t (yet) come across this in my reading, I want to note something that I think is important. When I captured the maps you see above, I thought it was important to highlight the context to which each level was related. If you look only at the bottom code level, you only see a building and a street (although I did make it a point to also capture the street name and route number). If you don’t know what city or state this place is located, then this macro level is likely useless information. The same is true for technical documents. Each small piece fits into a larger puzzle. If you don’t understand how the puzzle piece fits, you don’t get a sense of how the piece relates to the rest of the puzzle, and it becomes confusing and hard to follow.
As I said, I’m still reading about this, so I’m not yet sure what additional intricacies about the methodology I need to learn. Nevertheless, the concept does sound interesting, and I’m looking forward to learning more about it as I improve my skills as a technical communicator.
I’ve been building Confluence pages as my initial projects for my (still-relatively) new employer. I’ve been building landing pages, coming up with designs and layouts as I go along.
For a couple of these pages, I wanted to come up with graphics — not just to be aesthetically pleasing, but also to give each page an identity. That way, someone visiting them can quickly and easily discern that that’s the employee resources page, or the architecture team page, or whatever page it is.
I’ve said before — and this is something that I preach as a technical communicator — that reading is work. It takes effort to read a piece of text and to comprehend it. If I’m writing a step-by-step guide, my rule of thumb is, if a step takes longer than a few seconds to understand, it has failed and must be rewritten.
Have you ever read a long piece of text (that isn’t a book you’re reading for fun) and realized how mentally tired you felt after reading it? For that matter, do you even want to read such a long piece of text? There’s a reason why people never read terms and conditions that come with applications. Take a look at all that black text, and tell me if you really want to read through it.
On that same note, it’s been often said — and it’s true — that a picture is worth a thousand words. A graphic will often convey information that’s often difficult to put into words.
Some logos are so recognizable that they are iconic: Apple, Coca Cola, Nike, Amazon, and the list goes on. If you come across a web page with one of these logos, you’ll almost instantly recognize what the page is about.
Even when I write these ‘blog articles, I try to choose graphics that are illustrative of what I’m writing.
That’s what I’m after with these Confluence pages that I’m building (they’re internal to the company, so I’m somewhat hesitant about showing them off). An employee can take a quick look at the page and know that (s)he is in the right place.
Granted, heading graphics aren’t always appropriate for every document (resumes, anyone?). However, if they’re used effectively, they can add a lot to a document and maybe even make it easier to read. Good graphics aren’t always about making something pretty; it can sometimes, in and of itself, convey a message.
As some of you might be aware, I’m the person who handles communications and branding for the Albany local SQL user group. As such, I’m responsible for sending out group announcements, updating the calendar of events, and maintaining whatever social media resources we might have.
Last week, I was preparing the announcements material for our April meeting, and in doing so, I took a long look at our “logo” (seen here on the right). There were many things that I found amiss. First, the logo, which we had had for several years — I’ve lost track of how long — was unwieldy and no longer representative of our group. Second, it used the PASS branding (and the REALLY OLD branding at that), which needed to be removed since PASS ceased operations in January. Finally, it was not dynamic — we were using it universally as a logo and an icon, and it really did not function well as such. I spoke to Greg and Ed, our user group’s co-admins, and got their blessing to come up with a new logo for our group. (Besides, I needed the design practice!)
I sat down and tinkered with some ideas. I tried out some fonts and visual schemes. Ideally, I wanted to incorporate some specific design elements: New York State, something representative of the Albany Capital Region where we’re located, a technical-looking font, and the universally-recognized (at least to data professionals) database icon. I wasn’t sure what kind of color scheme I wanted to use, but as it turned out, I started out using blue and gold for the fonts (which, unofficially, are considered to be New York State’s colors), decided that I liked them, and stuck with them.
My initial idea was to superimpose the user group acronym (CASSUG) over the outline of New York State; those are the designs you see here to the right. I tried a couple of different fonts, including one (which you see in the second image) that included NASA in the font name. (I decided that I liked the other font better.) I positioned the database icon over where Albany is located, which would satisfy my requirement of representing the Capital Region.
While I was generally happy with the results, I also wanted to take another approach. I downloaded a line drawing image of the Albany skyline and placed the CASSUG text logo underneath it. I liked the idea and decided to run with it; however, I needed to find another image, as the skyline image I used could potentially have violated copyright restrictions (I did not post it here for exactly that reason). I had to find another image, but I was unable to find one that I liked. I decided that the only way I could come up with a suitable skyline outline image was for me to create my own.
I opened MS Paint and hand-drew a simple representation of the skyline. I decided to represent four local landmark structures in the drawing (and anyone local to the Capital District knows that one of those structures had to be The Egg — it is the one landmark building that instantly identifies the Albany skyline, just as much as The Pyramid identifies Memphis, the Carrier Dome identifies Syracuse, or the Space Needle identifies Seattle).
I thought the outline came out fairly well, but I had to make sure that I did it justice, so I posted it to my Facebook and asked local friends if they could identify the buildings. (If you’re looking at the logo at the top of the page, the buildings represent, from left to right, the Corning Tower, the Egg, the State Capitol, and the Smith building.) The outline was not to scale and it wasn’t perfect, but it didn’t have to be; it just needed to be recognizable. Everyone correctly identified The Egg, and most people were able to correctly identify at least two of the four structures. That people recognized the skyline told me that I had done my job.
I placed the CASSUG acronym and accompanying text underneath the skyline outline. I wanted to make sure the acronym was spelled out for the benefit of those who wanted to know the acronym’s meaning. As a final design idea, I took the New York State outline, placed it to the right of the acronym, and superimposed the database icon on top of it.
The end result is the image that you see at the very top of this article.
I ran my ideas past the user group members, and people overwhelmingly said they liked the Albany skyline image.
I like how the image came out. I intentionally created a relatively large image (2830 x 1250px); you can create smaller images from a big one, but you can’t create big images from a small one. The image is versatile; for example, if we need a banner, we can use the acronym and text without the skyline; if we need a thumbnail, we can use the icon over NYS, and so on. I started updating our Meetup page with the new design, and I’ll incorporate it into other materials as well.
What do you think about my rebranding effort? Like it? Hate it? Let me know in the comments below.
I don’t think there’s an experienced web developer or DBA who isn’t familiar with the classic “Bobby Tables” XKCD cartoon above. Just about any time you mention “Bobby Tables” to most experienced IT people, (s)he will immediately know to whom you are referring. Most experienced web developers and DBAs are aware of SQL injection and will take steps to ensure that it’s addressed. Grant Fritchey has a presentation about SQL injection (you can view and download his slide deck here) in which he’s not shy about his desire to “kill Bobby Tables.” I’ve seen him present it at SQL Saturday, and I highly recommend it.
Of course, the keyword here is “experienced.” For people who don’t have that experience, and who build websites that connect to databases, I think it should be lesson #1. Today, I had an experience that reminded me of that.
Earlier today, my sister texted me, asking for help with editing SQL code. She asked me what I use to edit SQL. I told her I generally use SSMS, although you can edit SQL code with a straight-up text editor, if necessary (she is not a DBA, so I felt somewhat comfortable telling her this). She told me she had to clean up spam comments in her data.
That last comment immediately grabbed my attention. I then asked her, how are your security settings, and do you have data backups.
She told me: that IS her data backup.
If her earlier comment had gotten my attention, this one immediately set off alarm klaxons in my head.
I started thinking about what could have corrupted her data to this extent. I started asking questions about her admin setup (I should’ve asked her to make sure she wasn’t using “sa” or “admin” as her admin login — Sis, if you’re reading this, make sure you check this!), including her passwords. Her admin password was pretty secure (thankfully).
She then mentioned her website. I asked if her website was accessing her data. She said yes.
I asked her about Bobby Tables (admittedly, in my advancing age, the term “SQL injection” didn’t immediately come to my mind). Her response: “who?”
At this point, I was convinced that I had my answer. Her database had been corrupted through SQL injection attacks. I told her to make sure you address your SQL injection issue before you even think about your data backups. Worrying about your data backups before addressing your SQL injection issue is like trying to rebuild your house before you’ve put out the fire.
I’ve been talking about SQL injection all throughout this article. For a brand-new web or database developer who has no idea what SQL injection is, here’s a quick primer: it’s a data security attack in which a hacker breaches your database by sending SQL commands through your web interface. I won’t get too much into how it works; instead, here are a few links that explain what it is.
So consider this a warning to any fledgling developers who are interested in web or data development: data security issues, such as SQL injection (and there are many others) are a big deal and need to be considered when building your setup; it’s not as simple as just setting up your website and connecting it to a database. By not considering this when you first assemble your system, you might be setting yourself up for major issues down the road.
My first instinct would be to shut down this monstrosity of a system. However, it likely wouldn’t be a good idea to shut down what might be the only means for an applicant to contact the human resources department. That said, this system is so badly designed that it’s likely to deter anyone trying to apply for positions, anyway. That gives me two options: either leave it as is, or implement a simple temporary replacement. Personally, I wouldn’t want anyone else to experience the horror show that I experienced, so I would opt for a simple replacement. The simplest option would be “send your resume, cover letter, and the position to which you want to apply to <such and such email address>.” Or, if I wanted to kick it up slightly, I’d make it a simple form: name, email, and a place to upload your resume.
If I opted for the form option, that would preclude some back-end mechanism to handle it. The simplest option would be to take that form data and put it together into an email that would format it, attach the resume, and send it to an email address. Of course, this opens another can of worms. First, there’s the matter of security. Who knows what viruses or Trojan horses are lurking in an attachment? Most forms like these ask for specific file types — usually a Word doc or a PDF — so I’d only allow those formats. I would also make sure that all security and antivirus functions are up-to-date; if a message does include a virus, at least it can be caught at the email application level, and it would be a matter of the cybersecurity team to investigate it further.
Once the temporary option is in place, and the horrendous system is shut down, I’d look into whether it’d be better to implement a new system out of the box, or roll my own.
Let’s start with rolling my own. I’d likely look into something using a SQL Server or Azure back-end (probably the latter, since everyone seems to be moving to the cloud, although that would require some brushing up on my part, since I don’t have a lot of cloud development experience). I’d probably put together a .NET front-end. Security, of course, would be a major issue to address, since we’d be dealing with applicant data. I would make sure that applicant data can be saved and pulled whenever an applicant applies for positions, eliminating the need for the applicant to continually re-entering his or her information, other than his or her login information. Again, the point is to make it easier, not harder, to apply for positions.
That said, there are a number of turnkey options that might be able to do the job better than I can. ICIMS is a popular SaaS product used by a number of employers. I would also look into other CMS systems that might exist. Other than ICIMS, I’m not sure of other applicant systems that can do what is required, but I don’t doubt that other systems exist that can maintain applicant data quite well. In this case, I’d switch my role from that of a developer to one of an analyst or consultant; what steps would I take to implement such a system? It would depend on the system and the environment.
Regardless of what system is used and how it’s implemented, any of these solutions would be better than the disaster of an application that I experienced.
In my job hunt experience, I might have come across what may be the worst online job application I’ve ever experienced — so bad that I felt a need to write about it. I will not identify the institution, other than it is a well-known institution in the Albany Capital District. Maybe if a representative from this institution is reading this article and recognizes that it is theirs, they’ll realize what a horrible experience this is, and takes steps to fix this problem — and yes, it is a BIG problem. I consider this a case study in how NOT to set up an online job application.
In my job search, I started looking into specific companies to which I could apply, so I went to this institution’s web site. I went to their careers section, found a few positions that I thought were interesting, and started applying for them. This is where the horror show begins.
Most online applications that I’ve experienced generally have an option for you to create a profile that includes your identifying information, resume, background, and so on. Indeed, I had applied to this particular employer years ago, and they had such a system in place back then. I poked around to see if I could find my previous profile, but I couldn’t find any such link. I figured, no matter; they probably had my old email address back then, so I’d probably have to create a new one.
As it turned out, this was a red flag.
Throughout my past several months of filling job applications, I’ve gotten used to ATS systems that read your resume or LinkedIn profile and autofilled job applications based on your resume and profile. I’ve had mixed success with these systems with varying levels of frustration, but for the most part, they’ve saved me a great deal of time and effort with applying for positions.
Unfortunately, for this employer, there was no such system. I clicked the button marked “Click Here To Apply.” It took me to a page that had this interface.
(At this point, I want to point out the part that says “You may add additional positions to this application.” I’ll come back to this later, but let me say that  during this first run-through, I wasn’t thinking about other positions yet, although there were others that interested me, and  I did not see this on the first go-round. Those of you who follow my post regularly know how much I emphasize that “reading is work!!!” Again, hold this thought; I’ll come back to this.)
Okay. I clicked Continue. The next screen was the standard HR-ese about EEO and code of conduct. I clicked the requisite box and clicked Continue again.
The next screen asked me to fill out my name, address, email, and various other boxes (“have you ever worked for [name of employer] before,” etc.).
Wait a minute. It’s asking for my name. Shouldn’t it ask to upload my resume or connect to my LinkedIn account? I looked around, and there was no such button or link. Okay. I filled the requisite fields and clicked Save & Continue.
The next screen asked questions such as date available to work, salary requirements, relatives that work for (name of employer), and so on. Again, I answered what they asked, and once again, clicked Save & Continue.
The next screen displayed the following.
I took issue with this question, particularly with the “highest graduate education year completed.” I have a Masters degree, I went to school part-time, and it took me 4½ years to get it, taking a class per semester (and a summer session) as my schedule allowed. So does that mean I click 4 (as in it took me 4+ years), or do I click 1 or 2 (as it typically takes to get a Masters degree full-time)? It did not specify, and there were no instructions. I don’t remember what I answered (I think it was 2), so I went with my best guess as to what they wanted.
Directly under that question was this.
Wait a minute. You haven’t asked me to attach a resume. I suppose it’ll ask me later (I still don’t understand why it didn’t ask me to attach one at the very beginning). I clicked Save & Continue.
The next screen asked about job history.
I already have my employment history on my resume (which you still haven’t yet asked me to attach, upload, or link). You really want me to take the time to fill this in? This screen frustrated me; I’ve been working professionally for thirty years. You really want me to fill all of that in? And why aren’t you autofilling it from my resume (that you still haven’t asked for yet), like everyone else using ATS is doing? The application only asks for at least four years of employment history, but I’ve only worked for a few companies over four years, and it doesn’t tell the entire story of who I am or my professional history.
Nevertheless, the application system had me over a barrel, so I had no choice but to fill it all out. Let me emphasize that the form is not easy to fill out; all dates are drop-down selections (which, I should add, don’t work very well), they don’t auto-format fields such as phone numbers (e.g. they don’t limit area codes to three digits), and you have to fill out the fields for employer, title, job description, and so on.
I don’t know how long it took me to fill it all out. I’ll estimate that it took between fifteen and thirty minutes. It felt like several hours.
It next asked for personal references, if I had fewer than two employers. Since I definitely had more than two employers, and I didn’t feel like filling out more than I had to, I skipped this step. (And I should note: what if I worked ten years for only one employer? Yet another problem with how this application was put together. Whomever it was that put this together was obviously not thinking.) Again, I clicked Save & Continue.
At this point (step 8 of 12, according to the application), it asked to upload documents (resume, cover letter, etc.). It only allowed up to two documents (most other applications I’ve filed allowed for more than two). Okay. I added my resume and cover letter, and clicked Save & Continue.
Finally, it got to the point to review everything I’d filled out (very painfully, I should add). I clicked Save & Continue. Subsequent screens displayed the requisite EEO questions — race, veteran status, and so on. I clicked through the screens. My application was submitted.
At this point, I went back to apply for other positions that interested me. It was here where the employer’s application went from being frustrating to downright infuriating.
Almost all automated job applications send an email acknowledgement, so I looked for one after I finished the arduous procedure. I didn’t see one. After waiting for several minutes and poking around my email, I finally found this sitting in my spam folder.
It sent it as an attachment? No wonder why it was flagged by my spam filter. Since I trusted the sender (or, more accurately, I knew from where it had been sent), I went in and followed the instructions. Okay, fine. I downloaded it and followed the sign-in instructions. It had me sign into their system, where I found this message.
Granted, there was no identifying information (other than my email and the employer, which I blacked out in this screen capture). Now, I am all for data security and ensuring data is protected, but did this message warrant sending a secure attachment and requiring a login? I don’t think it was. I’ve gotten other emails from job applications that included more information that was sent less securely. One other thing I found infuriating was that there was absolutely no reference to the position that I had applied. I’ve been using my email to keep track of applications. How am I supposed to know to what position this refers? In my opinion, this message was not worth sending in a super-secure email. I felt that the mechanism they used to send this message was overkill.
I had seen other positions on the list that interested me, so I went back to apply for them. I figured that the system would take my information from the previous application and use it for the new application.
I figured wrong.
There was absolutely NO mechanism to refill all the information from the previous application. There was no applicant account function, no resume or LinkedIn ATS autofill function, nothing. If I wanted to apply for another position, I had to refill the ENTIRE application manually. Did I mention how painful and tedious it was to fill the application? It might as well have taken several hours to do so.
Now, remember earlier how I mentioned that there was a link to “add other positions to your application”? I did not see that the first time around. The next time, I tried it. The link brought me back to the ORIGINAL job search page. There was NO function to add any other jobs to an existing application. Nothing like that was anywhere to be seen. And if it did exist (and I’m not sure that it does), it is not obvious.
This application system design is so horrendous that it’s saying “f**k you” to applicants. It is doing more to drive applicants away than it is to make them want to apply for positions.
This is not the first time I’ve written about bad form design. However, this problem isn’t just about the form; it’s also about the entire application process. The design planning was poorly thought out, if it was done at all. There is no mechanism for autofilling fields. There is nothing to save applicant data. The forms are not intuitive. And I’m willing to bet large sums of money that either there was no end user or QA testing done, it was done shoddily, or test criteria were poorly defined.
I could keep going, but to make a long denunciation short: whomever it was that put this together has absolutely no business working on UX/UI projects.
The object of well-designed UX/UI and online forms is to make it easier, not harder, for end users. As an applicant, I found this process to be infuriating, not just frustrating. A process this bad will likely deter qualified applicants from applying to jobs. And if this system is that badly designed, these applicants are likely to question whether they want to work for this employer in the first place.
I’ve come across my share of bad design, and I’m sure you have as well. I’ve especially come across some egregious examples as a job applicant.
I came across one that particularly set me off. While poking around Indeed, I found a technical writer position for GitLab that interested me. Of course, most people who work in IT are familiar with GitLab, so they have a reputation. I read through the description, and it sounded interesting, so I clicked the button to “apply on company site.”
The page talks about the technical writer roles and responsibilities. It talks about the hiring process, it includes a salary calculator, and it even talks about benefits, including stock options.
Nowhere on the page was there any link to actually apply for the position!!!
If you don’t believe me, check out the link and see for yourself. No wonder why they need technical writers. I understand and appreciate GitHub’s reputation in the IT community, but this page is seriously making me question whether or not I really want to work for them.
GitHub is far from being the only offender. I came across another page that, even after they asked me to upload my resume, it still asked me to manually input my work experience. (Even worse, these were required fields; there was no way around this. What if you’re a student with no work experience?) After I hit Submit, it came back and told me there were errors. It had cleared out all the dates I’d entered (I had entered months and years), and it insisted that I entered days. Seriously, raise your hand if you actually remember what day you started or ended a job from years ago. I have enough trouble just remembering the month or year. It made me question how well their automated formatting really worked (if it worked at all). Once I filled those in (with the best guesses for days), it told me there was another error. I clicked the message, expecting it to show me where the error was. Nope. It just told me there was an error. I had to search the entire page to figure out what it was complaining about.
I’ve come across too many forms like this during my job hunt. I also remember coming across some very badly designed forms years ago from previous job hunts — some that were so badly designed that they discouraged me from applying for the jobs.
I’ve talked about making documentation easier for the end user, and this is far from the only article I’ve written about how bad design is a detriment to anyone who needs to follow instructions. UX/UI needs to be as painless as possible for the end user. If you’re a vendor, bad design can drive away customers. If you’re an employer, you run the risk of discouraging qualified applicants.
Like good documentation, good form design needs to be well-thought-out and well-designed. Don’t be the organization that lost customers because your forms were too arduous to use.
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.
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.
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!