Playing in the sandbox is important for documentation

While working on a user guide, I realized that I had administrative rights to the application I was trying to document. That was all well and good, except that I was trying to write a non-admin user guide, and I needed to know how someone who didn’t have admin rights saw the application. Fortunately, one of my co-workers sent me an application URL and a testing user login I could use that simulated exactly what I needed.

That brings me to today’s article. Many application development environments make use of a sandbox, or some other development, environment where a developer can play to their heart’s content — that is, some place where someone trying to test or develop applications can play with the app without having to worry about breaking anything important. That same testing environment is just as important for a technical writer.

Much of my work as a technical writer involves putting myself in an end user’s shoes. I’ll often go through an interface and document the steps a user might use, what a user might see on the screen, and the effects of certain buttons and links. One of my most frequent questions when I work on documenting an application is, “what happens when I click this?” After I do so, hopefully my next response isn’t “oh crap!”

This is why a tech writer needs access to a testing environment. Like application developers who need to test within a safe environment, a person documenting the system needs to be able to document the system and be able to do so knowing that (s)he won’t adversely affect the application by playing with the system.

I wrote previously that a tech writer can help an application developer, and vice versa. Indeed, the tech writer can function as an in-house QA analyst. In order to write good documentation, the writer needs a realistic environment in which (s)he experiences what an end user might see. Having a sandbox environment in which a writer can “play” provides exactly that type of environment. As an added bonus, not only does this allow the tech writer to produce better documentation, it allows that person to provide feedback regarding the application, which ultimately results in a better application.

Advertisement

Bragging about your accomplishments

It’s true that bragging about what you do — boasting, talking smack, and strutting around like a peacock — generally tends to be frowned upon. However, I was thinking about a situation this morning where, professionally, it is appropriate to brag about what you do.

Yesterday, I picked up a new LinkedIn contact. The person in question is a guy I see behind the counter at the corner Cumberland Farms every morning when I stop to get coffee. This is the same guy that commented on my shirt whom I mentioned a while back. He’s a college student studying IT and has worked mostly jobs like working the cash register at Cumberland Farms. Taking a quick look at his LinkedIn profile, you’d think that that was all he did. But I do converse with him whenever I see him, and what he does goes deeper than that.

He went to our last user group meeting, and he told me he’s looking forward to attending SQL Saturday next month. A while back, I told him that he should download a free copy of SQL Server Developer Edition and practice. He did so, and he told me that he’s been spending a few hours each day practicing his SQL skills.

It occurred to me that that’s the perfect thing to write about. What are you working on? What have you done? What did you come across? What have you learned? What questions do you still have? People, especially recruiters and managers, like to see things like that. It shows that you’re learning and accomplishing things, which reflects very well upon you. This is great fodder for a ‘blog or LinkedIn posts. You can mention these things on a resume, in a cover letter, or during an interview, and if you ‘blog about it, you can use that to back it up.

There is a difference between being an egotistical braggart and talking about your accomplishments. If you’re trying to get started in a career field, don’t be afraid to toot your own horn. By all means, go ahead and talk about what you do, what you learn, and even what you don’t know but want to learn. It demonstrates that you’re motivated, inspired, and interested — traits that potential employers like to see. While people don’t like people who seem to know-it-all, this is one scenario in which bragging about what you do is appropriate.

When you make it hard for your customers to respond

This morning, I had an issue with my LinkedIn account. I was trying to reply to a message, and I kept getting “Send failed.” That was all I got — there were no error codes, additional information, or symptoms. I poked around LinkedIn’s Help section, and came across this page for dealing with messaging problems. I didn’t go as far as to clear my cache, but I did log out and back in, and I tried it in a different browser, all to no avail. In the middle of contacting LinkedIn’s support, the problem mysteriously “fixed itself.” If you work in tech, I don’t have to tell you how frustrating it is for an issue to mysteriously “fix itself.”

However, the issue I had, in and of itself, is not why I’m writing this article. When I heard back from LinkedIn, I got a message saying “go to this page” (the one I’d already found) and use that to troubleshoot. In response, it displayed the interface you see above. As you can see, they only gave me two options: “yes, I’m good,” and “no, I still need help.” The problem was, my response was, neither. No, I didn’t need help at that point, but I also wasn’t completely good, either. I wanted to inform them what had happened in case they wanted to investigate it further. But they did not give me that option. Between those two options, I clicked “yes, I’m good,” which immediately closed the case; I had absolutely no recourse to add more to it. I looked around for ways to send feedback, but I did not find any good way to do it. Replying to the email resulted in a response saying “you responded to an unmonitored mailbox.” The more I looked for a feedback mechanism, the more frustrated I got. The issue quickly went from “I’m reporting a technical issue” to “you guys need to fix your UI/UX.”

I’ve written before about how critical it is to get feedback, and how design can be a big deal. As much as I like LinkedIn as a business networking tool, I felt that LinkedIn fell short on both of these facets.

Let me start with the UX/UI design. I strongly felt that only those two options, especially if answering “yes” automatically closed the case, was a very poor design. As many people will tell you, the answer often isn’t simply “yes” or “no.” (One of the long-standing jokes among DBAs is that the standard DBA answer is, “it depends.”) And even after I clicked one of those buttons (in this case, I clicked “yes”), the interface was confusing. I was brought to a page that said “click to enter more information” (or something like that). The problem was, click where? None of the “links” allowed me to enter anything else, and there was no clearly logical eye path for me to follow. I had no idea what I was supposed to do once I got to that page. I kept clicking different links, trying to leave feedback. By the time I found a link, I wasn’t even sure that I was replying to my original query. I had no idea to what — or even where — I was responding.

I’ve said time and again that if you’re a technical writer — or a UX/UI developer — you don’t want to make your reader or end user work. Reading is work. Making your end user work is a sign of poor design.

Second, this experience made me question just how seriously LinkedIn takes feedback. True, nobody wants to hear bad feedback. I know I sure don’t. But if you want to improve, you need to know what it is you need to improve. How am I supposed to improve something when I don’t know what it is that I’m doing wrong? Not including a channel for feedback — or making it difficult to do so, as I allude to above — is doing a disservice to your organization and to your clients.

Good communication between you and your client is important. Not only does it help your client, it helps you improve your organization, and it builds trust between you and your customers. Making it difficult for your customers to communicate alienates them — and ends up hurting your business in the long run.

Business cards: the most important networking tool

At Albany SQL Saturday this year, I will be doing a lightning talk about what may very well be the most important item you could have for networking. This article outlines what I intend to discuss.

Why do I consider business cards — such innocuous little items — to be the most important item for networking? Let me lay out this scenario.

Let’s say you’re attending an event like, say, SQL Saturday. You manage to strike up a conversation with this person you happen to meet there. (S)he tells you that (s)he is a high-level executive for a company that hires people with the skill sets that you have. You tell him/her about yourself and what you do. (S)he becomes very intrigued. (S)he tells you, “let me get your name, number, and email, and we’ll talk!” You eagerly look for a pen and a piece of paper to write down your contact information, but you can’t find any readily available. (S)he says, “don’t worry about it. Track me down later when you have a chance to write it down.” Only that opportunity never happens. (S)he gets a call and needs to leave the conference before you have a chance to give him/her your contact info. A few days later, both you and (s)he have already forgotten each other’s names.

Opportunity knocked, but you didn’t answer the door. That could’ve been the job opportunity that kicked off your career — and you just let it slip through your fingers. If only you had a way to quickly and easily share your contact information — something that you can exchange instantly. Well, there is.

Business cards are small, simple, easy to carry, and easy to distribute. They’re much easier to carry than, say, copies of your resume. People don’t need to remember your name, email, or phone number. They also save the time of having to find a pen and paper or pulling out your smartphone and texting someone your contact info. Additionally, you cut out the extra step of having someone look up your contact info. The less you have to make someone work, the better.

Open up my business card, and you’ll see a little mini-resume!

Years ago, I decided to get creative with my business cards. One day, I came up with the idea of “baseball cards… business cards” and put the two concepts together. I had an old souvenir photo of myself in a baseball uniform that I used for the card photo. Flip the card over, and you’ll see my contact info (including my ‘blog, LinkedIn, email, and snail-mail addresses and phone numbers). Open it up (it’s a folded business card), and you’ll see my “career major league batting stats” — in actuality, a little mini-resume!

When I first designed and created these cards, I designed them in a MS Word template and printed them out onto business card stock. These days, I implement my design in a VistaPrint account and let them take care of the printing and card stock. I’ve found VistaPrint to be much more convenient than having to buy card stock and producing them myself.

To this day, I continually get rave reviews about my business cards, and I love the reactions I get when I pass them out. One recruiter told me that they have my card tacked on their “good ideas” bulletin board. A friend who was a (now-retired) career counselor asked me for a card so that he could show people, “if you’re looking for a job, this is the kind of thing you have to do.” Another person whom I met at a job fair told me, upon seeing my card: “I’m not in a position to hire, but if I was, I would hire you right now just because of this card!” Even Matt Cushing brings up my card whenever he does his networking presentation! My card is designed to do more than just provide my contact information — it shows off my creativity, that I can think out of the box, and it makes a good conversation piece. It makes me memorable, and ensures that I’ll be remembered in a good way!*

(*Well, unless you’re a Red Sox or Mets fan!)

Granted, you don’t have to create a baseball-business card (hey, my idea, darn it!), but don’t be afraid to get creative with your card design. You’ll more likely to be remembered. If you don’t feel like being creative with your cards, at the very least, have a basic card with your name and contact info on it that you can pass along.

A big part of networking is ensuring you can continue (or establish) a conversation at some point. Having business cards to distribute can ensure that the conversation — and possibly your big break — happens.

Who has the final say on a service issue?

I recently registered for Homecoming Weekend at the old alma mater. For me, it’s a reunion year ending in zero, so this year is of particular interest to me. (No, I won’t say which one it is. All I’ll say is, I’m getting old!)

While going through my own information on the Homecoming web site, I noticed a minor error. It wasn’t particularly big, and the error isn’t important in and of itself, but the university wouldn’t let me change it online; I needed to email them to get it fixed.

In response, I received a Jira service request notification indicating that it was in the queue. I knew right away that they were using Jira; we also use it in our office, and the email format and appearance is unmistakable.

The next email I got from them, a couple of hours later, is the graphic you see above, and as someone who’s worked in technology his entire professional career, I found it to be particularly irksome. When I received the message, my immediate thought was, “excuse me, but I am the customer. Who are you to say that my issue is resolved and completed?!?”

Sure enough, when I checked my information again, it still hadn’t been updated. I even tried clearing my cache and refreshing the browser. No dice. I wrote back, saying that I didn’t see the change and asking how long I should wait before I saw it. For all I knew, the web server had to refresh before any data changes appeared, so I gave it the benefit of the doubt. I received an automated message saying the case had been reopened (I was responding to Jira, after all). I didn’t get another response until this morning, when once again, it was marked “Resolved” and “Complete.” When I checked my information again, the change was there. I did not receive any other communications or acknowledgements, other than the automated Jira responses.

In their defense, to me, a department called “Constituent Records” sounds more like a data end-user role, rather than a full-blown IT or DBA role (I could be mistaken), so maybe they weren’t versed in concepts such as tech support, support levels, incident management, or support procedures. Nevertheless, I still found this to be annoying on a couple of levels.

First, it is up to the customer, not the handler, to determine whether or not an issue is resolved. The word “customer” can have a number of connotations*; in an internal organization, the “customer” could be a departmental manager or even your co-worker sitting next to you. To me, the “customer” is the person who initiated the request in the first place. An issue is not resolved until the customer is satisfied with it. It is not up to the handler to determine whether or not an issue is resolved. The handler does not have that right.

(*Side thought: the customer and handler can be one and the same. If I come across an issue that I’m working to resolve, I am both the customer and the handler. Nevertheless, the issue isn’t resolved until I, the customer, is satisfied that I, the handler, took care of it to my — the customer’s — satisfaction.)

Second, as a technical communicator, I was annoyed by the complete lack of communication from the person handling the request. The only communications I received were either comments contained within the Jira ticket or automated responses from Jira itself. Not once did I receive any message asking for any feedback or asking to see if I could see the change. The only messages I received — before I responded saying I didn’t see the change — was an automated Jira response acknowledging that they had received my request, and a second message that it had been resolved and closed. Boom. End of story.

I’m writing this article as a lesson for anyone working in a support role. First, feedback is important. You need to know that you’re handling the issue correctly. “How am I doing?” is a legitimate question to ask. Second, it is not up to you, the handler, to determine whether or not the issue is resolved. That right belongs only to the client — the customer who initiated the request, and whose issue you’re handling.

A SQL Saturday travel primer for first-time speakers

Are you a first-time SQL Saturday speaker? Congratulations!

Are you traveling to speak at your first SQL Saturday? Congratulations, again! You’re nervous, you say? That’s certainly understandable. Traveling for the first time to speak someplace you’ve never been can be daunting, but as I wrote previously, you need to step out of your comfort zone to get ahead.

I remember the first time I traveled to speak at SQL Saturday: Providence, RI in 2015. It was only the second time I’d ever spoken at a SQL Saturday; the first was within the friendly confines of my home town earlier that summer. This one was a little more intimidating for me; it was my first SQL Saturday (either speaking or attending) outside of New York state, I was in an unfamiliar town, and I was alone (I only knew one other person at this particular event). I was confident in my own abilities, but nevertheless, I’d be lying if I said I wasn’t a bit nervous. If you were speaking at your first out-of-town event, I’m sure you would be, too.

Well, since I started speaking at SQL Saturday almost four years ago, as of this article, I’ve since spoken at nineteen (and counting) SQL Saturday events in ten different cities in six states (seven, if you include DC*). I think I can safely claim that I am now a seasoned veteran when it comes to speaking at out-of-town SQL Saturday events (yes, several people have been to more than me, but I digress). And I’ve picked up some experience along the way. Here are some things I’ve learned during my travels as a SQL Saturday speaker.

(*Okay, DC SQL Saturday was technically in Chevy Chase, MD. However, DC was literally across the street. See for yourself!)

Before we start, let me direct you to a previous article I wrote about what it’s like to travel to a SQL Saturday. That should give you a taste of what it’s like to travel to speak at an event.

Now that your appetite (hopefully) is whetted, here are a few things to expect when you’re traveling to speak at SQL Saturday.

You’re doing this on your dime. Keep in mind that SQL Saturday is an all-volunteer event — and that includes you, the speaker. The costs for transportation, lodging, and food are all coming out of your pocket. It’s possible that you might be able to have your employer foot the bill for your trip — for example, if your employer is a sponsor, it’s possible that they could foot your bill as a duly-designated representative of the company.

Unfortunately, not every speaker has this option. For those of us who don’t…

AirBnB is a wonderful thing. Often, a hotel costs more than I want to pay. If you’re only looking for a place to lay your head and aren’t picky about a front desk, room service, or a concierge, I’ve often found rooms on AirBnB for a fraction of the price of a hotel.

And of course, if you want to stay in a hotel, it pays to shop around.

I’ve also attended a number of SQL Saturdays in cities where friends live. I’ve often asked them if I could crash in their guest room, or even their living room couch. For SQL Saturday in Philadelphia, for example, I have a college friend who lives near the event site, and I’ve stayed with him and his family every time I’ve attended this event. I’ve done this often enough that I no longer need to use my GPS to find his house.

How are you getting there? So far, I’ve traveled to all out-of-town SQL Saturdays either by driving or taking the train. I have yet to attend an event that requires me to fly there. (I did set a goal this year of speaking at an event where it isn’t feasible for me to drive. I’m hoping that that event is PASS Summit. We’ll see!)

Why don’t I fly to these events? Well, partially, it’s because I don’t like the hassles that come with flying. But as for my primary reason, go back and read the above paragraph about doing this on my own dime.

Make it an experience! My wife has an open invitation to travel with me to these events. She doesn’t come to all of them, but when she does come with me, we’ll often make an experience out of it. When I was chosen to speak at Virginia Beach, knowing that there’s a lot of touristy-type things to do in the area, I told her, “let’s take a few extra days and make a vacation out of it!” We went to Colonial Williamsburg and went to the beach, and we had a great time!

Network, network, network! Nearly four years ago, I traveled to Providence knowling almost no one there. Since then, I see many other SQL Saturday speakers fairly regularly, and I’ve become good friends with many of them. Even to this day, I continually make new network connections whenever I attend these events. Take advantage of the networking contacts you make, and bring business cards if you have them!

Above all, have fun! There’s a reason why I keep applying to speak at SQL Saturday. I could write more about the networking contacts, the data training, and the boost to my resume. But above all, I love doing these events. I genuinely enjoy attending SQL Saturday! I would attend more if my schedule and my budget (and my wife!) allowed it, but I try to attend as many as I can.

So if you’re looking to present at SQL Saturday events, go ahead and apply to a location that looks interesting to you. Hopefully, I’ll see you at one sometime soon!

Upcoming speaking engagements (as of 6/17/2019)

It’s been a fun year for SQL Saturday so far! I’ve spoken at three SQL Saturdays and two user group meetings so far this year, and more speaking engagements are on the horizon.

As of today, I am only confirmed to speak at one SQL Saturday, but it’s a big one.

• SQL Saturday #855, Albany, NY, July 20: this is my hometown event, and I’m always honored to be presenting in my own backyard! I will be doing a brand-new presentation, about ‘blogging. (No, I still haven’t finished my slides yet!) Additionally, I got the official word this morning that I will be also be doing a lightning talk. I will do a ten-minute talk about what I think might very well be the most important business networking tool you could have.
  
  Come on out and see me present in my home turf! Use the link above to register for this great event!

There are also a number of events to which I’ve applied to speak. I may not know for a little while as to whether or not I’m picked, but so far, the list includes these events.

• SQL Saturday #892, Providence, RI, August 24: When I spoke to John Miner (who is organizing this event) in Virginia Beach last weekend, he sounded pretty certain that I would be speaking. I don’t want to say too much until I get the official word, but nevertheless, this is a good event to attend. Providence is always a good one!
• SQL Saturday #912, New York City, October 5: I’ve attended SQL Saturday in NYC more than any other event, going all the way back to my very first one in 2010! I’ve only been selected to speak there once (last year). Let’s see if I’m picked again.
• PASS Summit, Seattle, WA, November 5-8: This is considered the “Super Bowl of SQL Saturdays.” I’m hoping!

SQL Saturday/PASS events are always a good time, and I tend to give pretty good presentations (or at least I’ve been told as much). Hopefully, I’ll see you at one near you sometime soon!

Major League Baseball in Troy, NY

A friend of mine pointed out that a Wikipedia article about the Troy Trojans baseball team cited me as a reference!

The article was actually a project for a Writing for Publication class that I took in grad school. It was later republished as a feature article in a baseball preview issue published by The Spotlight News.

However, when I looked at the Wikipedia reference link, I realized that the link was an old one that I’d forgotten about, and didn’t know was still there! I figured I should give the article a new home. So I took my article and created a new page for it. You can find the new article page here!

The article is a neat history piece that dates back to a period around the Industrial Revolution. If you’re a baseball enthusiast (like I am), I hope you enjoy it!

Don’t like reading terms and conditions? It’s not just you

During my lunch break, I came across this article in the New York Times. It talks about privacy policies for a number of companies — and the vast majority of them are nearly incomprehensible. According to the metrics in the article, comprehending privacy policies requires a minimum of a college degree — and even then, they may not be understandable. As mentioned in the article, the policies were not written to inform the public (read: you) as much as to protect the company. It brought to mind a research article that I read in grad school. It had to do with legal documents, the language of legalese, and how it was nearly incomprehensible. I don’t remember the specifics of it (grad school was a long time ago), but the gist of it was that these documents were purposely written that way in order that any ambiguous language was eliminated and things were made clear. And when I say “clear,” I mean that definitions were defined and unequivocal. Readable, however, is another story.

I could get into data security and how privacy policies exist for your protection, but that’s not why I’m writing this article. (I’ll leave it to people like Steve Jones to address that aspect.) Rather, I’m writing this because I’m a technical writer (among other things), and document readability is a big deal to me. Indeed, this is a major point of emphasis in both of my presentations about talking to non-techies and documentation, and is one of my biggest document pet peeves.

Readability is a huge deal in documentation. Legalese may be a big deal for making sure definitions are unambiguous, but it is inappropriate for something like, say, step-by-step instructions. When I’m writing instructions, I follow a rule of thumb where if an instruction takes longer than a few seconds for the reader to understand, the instruction has failed. I continue to be appalled by technologists who insist on writing every little bit of detail in their instructions and end up with a “step by step” that is one big black body of text. And I’m continually annoyed when that person says, “it’s right there in the documentation,” but the information you seek is buried somewhere in the middle of the 100+ lines of text that (s)he wrote that takes about an hour to read.

When I talk about documentation and instructing people, one tenet that I actively push is the KISS principle. But even this is not easy to do, and people take that for granted. Indeed, this is what technical writers, UX/UI developers, and instructors do; they are in the business of taking incomprehensible technical language and translating it for people to understand.

Do privacy policies really need to be that incomprehensible? I don’t have an answer to that right now; that might be another article for another time. But what I do know is, if their intent is to inform people, especially the general public, they fail miserably.

SQL Saturday Virginia Beach — the debrief

My wife and I arrived home in Troy, NY around 10 pm last night after driving all day from Norfolk, VA. Despite the lengthy drive home from Virginia, it was, nevertheless, a fun and fruitful trip!

First, Greg Moore, who also attended SQL Saturday #839, summed up his assessment of the event in his article here. Go ahead and read his article. I don’t think I could’ve summed it up much better than he did.

As is the case with most SQL Saturday events, I had a chance to network and connect with a number of people. Most notably, I had the opportunity to meet Andy Leonard, who has written a number of books, writes frequently for SQLServerCentral, and is considered a rock star among SQL circles. I told him about my writing exploits, and he hooked me up with the editor at Apress publishing. Once I’ve had a chance to get everything settled and back into the normal routine after nearly a week away, I’ll have a conversation with him. Could a book be in my future? I’ve always dreamed about having my name on a book. We’ll see!

My own presentation went well, although I still think it could be better. This was the first time I’d given this presentation since I revamped my slides. I’ll have to see what feedback I received and use it to make the presentation even better.

I met a fellow fraternity brother who recognized the letters on the hat I was wearing!

I also had another textbook example about how your clothing can initiate a networking opportunity! On Friday, my wife and I were enjoying the Norfolk Harborfest. While walking through the park, a guy recognized the letters on the baseball cap I was wearing, and came over to say hi! He was a fellow fraternity brother from the chapter at Norfolk State University. We took the photo you see above. Always a pleasure to meet another fraternity brother!

The rest of the trip was a great time! I knew that there was a plethora of activities around Norfolk/Virginia Beach, and suggested to my wife that we make a vacation out of it. We hit Colonial Williamsburg, the Chesapeake Bay Bridge-Tunnel, and the beach while we were there.

Although it was a lengthy trip, it was a good one! I look forward to doing it again at some point!