User testing is important — for documentation

Any application developer will (and should) tell you how important end user testing is for their product development. It’s an important part of the development lifecycle. Developers need to know if their applications actually work, if they work the way they’re intended, and if their interfaces can actually be used. Without user testing, developers put blind faith in what they produce, and they have to assume that their applications are perfect every time, all the time — which, as we all know, always happens. User testing is critical in ensuring that you create a quality product.

So how often does your documentation go through user testing?

I’ve said many times that document development needs to go through the same steps as application development, and this is one of those steps. It is (sadly) common for documentation to be released without being checked for accuracy or usability. This is another way in which document development gets absolutely no respect, whatsoever.

If you’ve written, say, a set of instructions, one of the best things you can do is to give it to someone to make sure (s)he can follow it. How (s)he follows it readily tells you how well it was (or wasn’t) written, what does and doesn’t work, what adjustments need to be made, and so on.

It may not even entirely be the wording that needs adjustment. How easily did the person find information within the document? Was it there but not easily found? Was it overlooked? User testing not only can determine content accuracy, it can also serve the same purpose as UX/UI in that it can determine how effective object placement and document layout is.

And like application development, user testing your documentation determines what adjustments need to be made before it’s released. Additionally, user testing isn’t just critical for development; it’s important for document maintenance as well. Documentation that hasn’t been adjusted for changed environments makes for inaccurate information. Much of that can be caught through user testing.

I’ve said time and again that document development needs to be treated the same way as application development. User testing is an important step in that life cycle. It determines that your document quality is improved when it is released. Without it, you run the risk of releasing bad, poor quality, or inaccurate documentation.

October CASSUG Monthly Meeting #Networking @CASSUG_Albany #SQLServer #UserGroups

Greetings, data enthusiasts!

Our October meeting will again be online. NOTE: you MUST RSVP to this Meetup at https://www.meetup.com/Capital-Area-SQL-Server-User-Group/events/281203246/ to view the Zoom URL!

Our October speaker is Josephine Bush!

Topic: SQL Auditing

Our online meeting schedule is as follows:

  • 6:00: General chat, discussion, and announcements
  • 6:30: Presentation

We usually wrap up between 7:30 PM and 8:00 PM.

Please RSVP to this Meetup, then use the online event URL to join (note: you MUST RSVP for the URL to be visible). We will send out a meeting password as we get closer to the event.

Thanks to our sponsor, Datto, for making this event possible!

When is “good enough” good enough?

If there’s one thing that I struggle with (and I’ll bet the house that I am not alone), it’s determining when something I’m working on is at a point where it’s “good enough for government work” (as the saying goes). Whenever I work on anything — whether it’s a work task or an extracurricular project — I always want to put in my best effort. As my personal mantra often goes, always put in your best effort — I don’t care if you clean toilets for a living. Ideally, my goal is perfection every time.

The problem is, perfection is an unrealistic standard. I’ve written about this before, and I still believe it. We’re human, after all, and a big part of being human is that we are rarely, if ever, perfect. I’ve often said that perfection as a goal is okay, but perfection as a standard is unacceptable. Sure, every once in a while, a bowler will bowl a 300 game, or a baseball pitcher will pitch a perfect game, but neither can be expected to do so every time out. Setting perfection as a standard is impossible, and anyone who sets perfection as a standard really needs to rethink their priorities.

For me, this is a constant struggle. I want to do the best job possible every time. However, there are often factors that work against me: deadlines, schedules, task management, work load, lack of knowledge or experience, fatigue, and so on. Additionally, my work often coincides with something else; a teammate is often counting on my part in order for him or her to proceed with their task. We don’t work in a vacuum; we’re often part of a team, and we need to work together. This is true even if you’re an individual contractor; your customer often expects to see results.

So how do you measure when something is “good enough?” This is often subjective and hard to answer, but I’ll take a crack at it.

I’ll use one of my favorite (and oft used) examples: baseball. As I mentioned above, a pitcher isn’t perfect every time. He’ll often give up a few hits and walks. He might even give up home runs on occasion. But was his performance good enough for his team to win? A play-by-play announcer will sometimes say, “he didn’t have his best stuff tonight, but he kept his team in the game, and it was good enough to get his team the win.”

So with that, I’ll often use measures like these: did my team get the win? Did my teammate (or customer) get what (s)he needed from me in order to do what they needed? Did my efforts meet the requirements? Did my teammate accept my results? Did my efforts get the job done? And, most importantly to me, did I give it my best effort, given any impediments (time constraints, fatigue, degree of difficulty, experience — or lack of — with the task, etc.) that might be in my way?

If I’m able to answer yes to questions like these, then in all likelihood, I can say yes, my efforts were good enough.

Never assume it’s obvious

When I was in college, I remember a professor who seemed fond of saying “it’s intuitively obvious.” I don’t remember a lot from that professor (other than that he was a good professor and a good man), but I vaguely remember my classmates making fun of that line, partially because he used it often, and partially because it often was not “intuitively obvious.”

How many of you remember way back when the “this beverage is hot” warning labels started appearing on coffee cups? Many of us (myself included) ridiculed it, responding with, “duh!” But of course, there is usually a good reason behind the story. Now the hot beverage warning label is ubiquitous on nearly all hot beverage cups, and most of us don’t give it a second thought.

I was reminded of this yesterday as I worked on a project. I won’t go into the details (I don’t like to share details of an in-house work project), so I’ll give you the high-altitude view of it. I’ve been trying to solve a problem where multiple people are asking IT Support for assistance, and IT Support is overwhelmed by requests. IT Support does have a website where many of these questions can be answered, but it seems that people either don’t know it exists or don’t know enough to look for the answers there.

I went poking through the website. It did seem to have the tools necessary to answer many questions, as well as resolve a few issues I’m working on. It then occurred to me — the very fact that I was poking around the site to figure out how it worked. In other words, it wasn’t entirely obvious as to how to get the answers from the site. It occurred to me that what was missing was a user guide for the site. I’ve been pitching it to several people, as I believe it’s a good idea, and I think it will resolve a number of problems. Nevertheless, I’ve gotten a little bit of pushback, along the lines of, “of course it’s obvious how to use it,” and “we have links everywhere that explains how it works.” (Also, IT Support, as just about any department, tends to get somewhat protective — understandably so — of its assets and material.)

So if it’s so obvious, then why are you getting overwhelmed with questions?

As a technical writer, “never assume it’s obvious” is one of my biggest mantras, and I think it should be for anyone involved with technical communication, UX/UI design, teaching, or documentation. Simple instructions can often be overlooked (how many times do I have to say that reading is work?!?), and people from other cultures may not always understand the language or context that you’re writing, so that’s something else to consider.

Never, ever, assume anything is obvious — because more often than not, it isn’t.

Improvement through rewriting

If you’re an application developer (or at least you used to be one, like me), how many times have you come across an old piece of code that you wrote and said to yourself, “what the f*%k was I thinking?!?” You say to yourself, I can write that much better now than I did back then, and your instinct is go back and change everything that you’d previously written.

The same holds true for documentation. I recently had an experience that reminded me of that.

I was updating my slide deck for my upcoming SQL Saturday talk this Saturday. I thought my slides were in pretty good shape, but I wanted to go through them to ensure that everything was still fresh and up-to-date. Besides, the organizers at SQL/Data Saturday LA sent me a link to their PowerPoint template, and I figured that I should use it for my slide deck for Saturday.

Indeed, when I went through my slide deck, I was hit with a case of “what the hell was I thinking?” Many of my statements and references were outdated. I found that I could rewrite much of what I’d originally written, making them more efficient and readable. Some items were unnecessary, and I eliminated them altogether.

I spent a couple of days rewriting my slides. When I was finished, I discovered that I liked the new slides much better than my old ones. I took the new slides and made some minor modifications (mainly removing the SQL Saturday LA branding so that it was more generic). If you’d like to see them, you can download them from my Presentations page.

So the moral of the story is, no matter how good you think something is, it can always be better. Don’t be afraid to review and edit something you’ve created. You might find that you like your new version even better.

(P.S. check out my presentation this Saturday!)

The right frame of mind is important for your overall health

I’ve been holding off on writing about this, but what happened to me is an important story to tell, and a cautionary tale for others who might be going through the same thing.

The photo you see above is me lying in a hospital bed about a month ago. And I want to tell you how I got there.

I have made no secret about how much the experiences of the past year have stressed me out. When I keep a regular schedule (and when I’m working), I have a routine that I maintain. And as long as I stick to the routine, I tend to do pretty well. If my routine gets upset, that’s when I get into trouble.

Well, the stress that I’ve endured upset my routine. My sleep schedule had been irregular. And I’ve been doing a terrible job of taking care of myself. The pandemic closure, in the early months, shut down gyms, which meant that I stopped going to CrossFit (which had been part of my routine). To make up for it, I started doing a Couch to 5K program. I had been doing pretty well with that program, until about halfway through, I was beset with injuries which also upset my (now new) routine. (The injuries were bad enough that I ended up going to PT to address them.) My extracurricular schedule, also part of my routine, had been disrupted because of the pandemic. I was stressed and overwhelmed. Things that I used to enjoy now suddenly seemed like a chore. To sum it all up, I had stopped taking care of myself.

About a month ago, I started having problems eating. Twice within two weeks, I got sick after eating. After the second time, my wife insisted that I go to the ER. Upon being examined, I was told, “we’re admitting you.”

For the sake of my personal privacy, I won’t say what it was that I had, except that it was not COVID. I will say that I remained in the hospital for a week. I barely ate anything during that week. My only diet was bags of IV solution that they sent through my system.

That was not a pleasant experience. I would not recommend that to anyone.

I have been home from the hospital for almost three weeks. I am slowly (emphasis on slowly) getting back to normal. Even as of this article, although I feel much better than I did, I still have not recovered 100%. My energy level is not what it was, and I get tired easily. And it all came about because I had become overwhelmed and had stopped taking care of myself.

The moral of this story is that your emotional and psychological well-being is just as important as your physical one; in fact, it can directly affect it. Your morale is important; in fact, it’s one of the things that I address in my job hunt presentation.

So take it from me. Take care of your mental well-being, and make sure you’re in the right frame of mind. Do what you need to do to roll with the punches. If you need to occasionally let off steam, do so. Get help if you need to. Get yourself to where you need to be, mentally and psychologically. Once you do that, you’ll be able to take care of yourself. Don’t end up like I did last month, and spend a week in a hospital bed.

Our user group logo gets a makeover @CASSUG_Albany #Logos #Branding

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.

Our old user group “logo”

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!)

One idea that I tried…
…and another

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.

What are you proud of? Tooting your own horn on your #resume — #JobHunt

Yesterday, a good friend of mine texted me, asking me to send him my resume. This particular friend works for a major nationwide consulting firm. I won’t say which firm, but I will say that it’s a household name. In his position, he is often in a position to hire, and he is well-connected.

After reviewing my resume, he texted me back again, saying “let’s talk. I have some ideas that might make your resume even better, and I want to make sure those changes are implemented before I pass your resume along. Do you have time to talk tomorrow?”

I got off the phone with him a little while ago, and what he had to say was eye-opening — and in our conversation, I managed to improve my resume even more.

His advice (and I’m paraphrasing here): “what projects are you the most proud of? As a hiring manager, that’s something that stands out to me. Your work experience looks good, but everything you mention is general day-to-day activities. You don’t really list much in terms of a specific project you worked on. For example, something like ‘I designed such-and-such app that helped people do their work more efficiently by whatever-it-did-to-help-them, saving the company millions of dollars’ is something that would stand out to me. What are you the most proud of? Make sure you highlight that in your resume.”

I did raise a concern. I told him, yes, there is a project that immediately pops into my head, but it goes back many years; in fact, it’s a project I worked on for a company that goes outside of the past ten years. He told me, “that doesn’t matter” (he also relayed to me a project that he was proud of that took place over twenty years ago). “I’m proud of that, and I still include that in my profile.”

I had my resume file open in front of me during our conversation. While we were talking, editing ideas started forming in the back of my head.

His suggestion was to include these projects in my work experience, but I decided to leave that section alone. Instead, I decided to rewrite the Career Summary section of my resume. I wanted to do it this way for a couple of reasons: one, this appears at the top of my resume and would be the first thing that prospective employers read, and two, rewriting the Work Experience listings would have been a lot of work, and could have potentially resulted in document restructuring issues.

In terms of projects in which I take pride, I immediately wanted to mention a server inventory database that I built years ago; whenever anyone asks me about a professional project of which I am the most proud, this is the one that I always think of immediately. I also wanted to mention my involvement with recovery efforts after 9/11 (my Disaster Documents presentation is based on this experience), so I included that on the list as well. I also wanted to include a project that was much more recent, so I included a user guide that I wrote from scratch, including developing the Word template for it (additionally, I wanted to highlight that it was for a SaaS application). Finally, I also wanted to make mention of a project in which I learned about MVC concepts (unlike the other projects, this one does appear in my Work Experience section).

There were also a few other things I wanted to do with my Career Summary section. A while back, I came up with my own personal tagline, but it did not appear in my resume. I wanted to make sure it was included. Additionally, whenever I submitted my resume, I was finding that I was experiencing confusion on the part of prospective employers. I was (and still am) targeting primarily technical writer positions, and I was often questioned, “with all this technical experience, why are you targeting tech writing jobs?” I wanted to restructure it in such a way to explain that I was drawing upon tech writing as a strength, without sacrificing the fact that I had a technical background.

Before I made my edits, the Career Summary section of my resume looked like this.

(The Career Summary section of my resume — before)

When all was said and done, this is how it came out.

(The Career Summary section of my resume — after)

Additionally, I had to make changes to other sections of my resume, entirely for formatting purposes. I wanted to ensure that it would fit on two pages. I consolidated a few sections of information that, while helpful, I didn’t think would be as important.

I made the changes, updated my resume files (Word and PDF), and resent it to my friend. As of this article, I’m still waiting to get his feedback (he texted me to say he was busy, but would look when he had the chance), but personally, I like the way these changes came out.

(Edit: I heard back from my friend; his advice was to keep the accomplishments to one line each. In his words, “make it punchier.”)

You don’t necessarily have to do this within your Career Summary section; this was how I decided to approach it. If you can incorporate these highlights into your work experience listings, then by all means, do so.

I want to mention one thing when adding “proud accomplishments” to your resume. There is a fine line between talking about accomplishments you’re proud of and bragging about things to stroke your ego. Keep in mind that the purpose of a resume is to get you a job interview. Talking about projects you did that made a difference can help with that effort. Bragging about things you did (or didn’t do) will not. Nobody cares about your ego; they care about what value you can bring to their organization.

So what are your thoughts on these changes? Feel free to comment on them, especially if you’re a recruiter or a hiring manager.

The Value of Paper vs Convenience of Digital

I wrote a while back that, while digital documentation dominates the world today, paper isn’t necessarily dead. That said, my friend, Greg Moore, notes an issue with printed material that didn’t occur to me, and it has to do with data security. Read on for more.

greenmountainsoftware

About 35 years ago in the fall, a housemate of mine got a phone call, “hey, I’m a caver who’s passing through your area this weekend and found your name in the NSS Members’ Manual, I was hoping maybe you could hook me up with a caving trip.” Well it just so turns out that the RPI Outing Club traditionally does Friday night caving. (Why night you might ask? Well it’s always dark in the caves, so going at night leaves time on Saturday and Sunday to hike, rock-climbing, canoe, etc.) My housemate invited the guy along and he joined us caving (I think in Knox Cave).

I mention this story because it’s an example of how the NSS Members’ Manual has often been used over the years. Talk to enough old-time caves (especially those who recognize the smell of carbide in the morning) and many will mention how they’ve…

View original post 1,404 more words

#SQL101: Raising awareness of SQL injection

(Image credit: XKCD.com)

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.

And make no mistake: SQL injection attacks can cause major damage.

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.