When it’s appropriate to use fake data (no, really!!!)

It isn’t uncommon for me to include data examples whenever I’m writing documentation. I’ve written before about how good examples will enhance documentation.

Let me make one thing clear. I am not talking about using data or statistics in and of itself to back up any assertions that I make. Rather, I am talking about illustrating a concept that just happens to include data as part of the picture. In this scenario, the illustration is the important part; the data itself is irrelevant. In other words, the information within the data isn’t the example; the data is the example. Take a moment to let that sink in, then read on. Once you grasp that, you’ll understand the point of this article.

I need to strike a type of balance as to what kind of examples I use. Since I work in a multi-client data application environment, I need to take extra steps to ensure that any data examples I use are client agnostic. Clients should not see — nor is it appropriate to use — data examples that are specific to, or identifies, a client.

There’s also a matter of data security. I needn’t explain how big of a deal data security is these days. We are governed by laws such as HIPAA, GDPR, and a number of other data protection laws. Lawsuits and criminal charges have come about because of the unauthorized release of data.

For me, being mindful of what data I use for examples is a part of my daily professional life. Whenever I need data examples, I’ll go through the data to make sure that I’m not using any live or customer data. If I don’t have any other source, I’ll make sure I alter the data to make it appear generic and untraceable, sometimes even going as far as to alter screen captures pixel by pixel to change the data. I’ll often go through great pains to ensure the data I display is agnostic.

I remember a situation years ago when a person asking a question on the SQLServerCentral forums posted live data as an example. I called him out on it, telling him, “you just broke the law.” He insisted that it wasn’t a big deal because he “mixed up names so they didn’t match the data.” I, along with other forum posters, kept trying to tell him that what he was doing was illegal and unethical, and to cease and desist, but he just didn’t get it. Eventually, one of the system moderators removed his post. I don’t know what happened to the original poster, but it wouldn’t surprise me if, at a minimum, he lost his job over that post.

Whenever I need to display data examples, there are a number of sources I’ll employ to generate the data that I need.

  • Data sources that are public domain or publically available — Data that is considered public domain is pretty much fair game. Baseball (and other sports) statistics come to mind off the top of my head.
  • Roll your own — I’ll often make up names (e.g. John Doe, Wile E. Coyote, etc.) and data wherever I need to do so. As an added bonus, I often have fun while I’m doing it!

Are there any other examples I missed? If you have any others, feel free to comment below.

So if you’re writing documentation in which you’re using an illustration that includes data, be mindful of the data in your illustration. Don’t be the person who is inadvertently responsible for a data breach in your organization because you exposed live data in your illustration.

Advertisements

#SQLSaturday #892 Providence — the debrief #SQLSat892 #SQLFamily

I arrived home last night around 9:15, after driving four hours (including an hour-long dinner break) from Providence, RI. As usual, it was another great SQL Saturday! As always, I had a blast! And as always, I was wiped out after it was over! Even as I write this, on this Sunday afternoon, I had intended to take care of some work around the house, and ended up taking a nap instead. C’est la vie.

So as seems to be tradition lately, here’s my most recent writeup of my most recent SQL Saturday.

I’ll start with something I did before I even left on Friday. I was getting my things organized and packed for my trip. While going through my briefcase, I came across my laptop dongle. I told myself, “most places these days use HDMI video inputs for their projectors. I haven’t needed it yet. So I’ll just leave it here.” I tossed it back in my briefcase, and packed my laptop without the dongle.

I didn’t know it yet, but I had just shot myself in the foot. (Read on, McDuff.)

Image may contain: 18 people, including Raymond J Kim, Ed Pollack and Paresh Motiwala, people smiling, people standing, people sitting and indoor
SQL Saturday speakers at dinner (photo courtesy of Paresh Motiwala)

I checked into my B&B (a cute New England cape house in North Kingstown, RI) and headed to the speaker’s dinner. One of the B&B’s co-owners told me that the restaurant was a former train station. It sat by some very active railroad tracks. Not only was I able to see trains as they went by, I could feel them. Several Amtrak, Acela, and MBTA commuter trains passed by during dinner.

Image may contain: 5 people, including Paresh Motiwala and Raymond J Kim, people smiling, people standing
Of course, it isn’t a SQL Saturday unless Paresh and I go out for ice cream!

My session was scheduled for 10:00 on Saturday. Unfortunately, it didn’t go as smoothly as I would have liked. For starters, I found out that the wrong room was listed on the schedule. I went to an empty room, which surprised me, because I was expecting to walk into the previous session already in progress. It turned out that it was down the hall.

Remember how I said that I shot myself in the foot when I didn’t bring my dongle? Here’s where it raised its ugly head. It turned out that the only projector connections were VGA, which I didn’t have on my laptop. I was not able to find an HDMI adapter. That’s when I resorted to Plan B.

Before every SQL Saturday, I always make it a point to upload my slides to the website. They’re there so that attendees can download them. However, they also serve a secondary purpose: my backup, in case something happens with my laptop. Sure enough, I had to resort to it. I used the desktop computer in the classroom, downloaded my slides, and used that for my presentation. (A thought popped into my head while they were downloading: does the desktop have PowerPoint installed?)

I was angry with myself, because I usually take pride in that I’m always prepared — and on this day, I wasn’t. Note to self: always bring the dongle with you. I made a mistake, and I paid for it by losing ten minutes of my presentation time. I suppose I’ll chalk it up as a learning experience, and remember to pack my dongle for next time.

The presentation otherwise went without a hitch. I did tweak it a bit, per the feedback I received the previous time I’d presented it.

Image may contain: 2 people, including Raymond J Kim, hat and outdoor
I’ve conversed with this gentleman online for years — and finally met him in person for the first time at SQL Saturday!

I was in for a surprise (a pleasant one, this time!) after my presentation. One of the attendees (the gentleman you see in this picture) introduced himself to me after I was done — and when I saw his name tag, I realized immediately who it was! (For privacy reasons, I’m withholding his name.)

I often peruse the forums on SQLServerCentral.com. It’s my go-to forum whenever I have database-related questions. There are a number of people whom I see regularly on the forum, and I interact with them often enough that I consider them friends. The fantasy football league in which I play came from these forums. There is one person with whom I interact regularly on the forums, including fantasy football. He is our league’s defending champion, and as the only two people in the league who have multiple titles, we are rivals. I’ve been conversing with him for year and years. I consider this man a friend.

This weekend, we met face-to-face for the first time! He attended my presentation, and I had no idea that it was him! His attendance totally blew my mind, and it made my day!

Grant Fritchey gave a great presentation about SQL injection. It blew my mind — and not in a good way. Although SQL injection was identified as a security problem in 1997, it still persists as a problem now in 2019. If nothing else, Grant’s presentation reminded me that we still need to be vigilant about fighting code injection, even with all the safeguards we have in place now.

Probably one of my favorite sessions was the last one of the day. Linda Groszyk, who is a relative newcomer to speaking for SQL Saturday, gave a great presentation called Breaking the Social Code: How to be Socially Intelligent at Work. It was a fantastic session about human psychological dynamics that, I think, everyone should be aware of. I was impressed enough by her presentation that I encouraged her to apply to speak at our SQL Saturday in Albany when it rolls around next July, as well as our user group, if she is able to arrange it! (Greg Moore, if you’re reading this, consider this a heads-up!)

Another weekend, another great SQL Saturday in the books! If you are able to make it to one near you, I encourage you to do so!

Ransomware and DevOps

Another post by Steve Jones that I think is really important…

Voice of the DBA

Ransomware.

A scary topic and one attack that is apparently more common than I suspected. Before you go further, if you haven’t restored a database backup in the last month, stop and go verify your DR plan works. That’s one of the overconfident issues facing lots of government and businesses. While this might not help your entire organization, at least you’ll have some confidence in your process and that you can recover a database.

This is a great article from Ars Technica and worth reading: A take of two cities: Why ransomware will just get worse. I’d recommend you read it and think about a few things. First, do you have insurance because things (or substitute your own word here) happen? Second, have you really tested a DR plan for some sort of software issue like this? You might think about a way to restore systems in an air-gapped…

View original post 356 more words

July 20 — SQL Saturday, Albany, NY

On Saturday, July 20 (one week from tomorrow), the Capital Area SQL Server User Group (CASSUG) will host SQL Saturday for the sixth time in Albany, NY!

For those of you who are not regular readers of my ‘blog, SQL Saturday is a daylong conference centered mostly (but not entirely) around data topics related to SQL Server. It’s also a great networking event, and an opportunity to hook up with a number of data professionals! Check out the schedule to see what sessions interest you!

And yes, I am presenting, too! I will do a brand-new presentation about ‘blogging, as well as a lightning talk about business cards! I always look forward to doing presentations in my own backyard!

Additionally, there are three pre-con sessions on Friday, July 19. Unlike SQL Saturday, these sessions are not free, but they provide quality daylong training for specific topics at a decent price. Information about these pre-cons can also be found on the web site!

For more information and to register for the event, visit our website! Upstate New York is a great place to visit during the summertime! Hope to see you there!

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.

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.

Testing something? What’s the test plan?

Imagine if you will that you’ve been asked to test a product. The product could be anything — software, a car, a kitchen appliance, a piece of sports equipment, whatever. For the purposes of this article, we’ll say you’re working at some company, and you’ve been asked to test a piece of software.

You’re told to go into an application, and you’re given this instruction.

“Okay, test it and see if it works.”

That’s it.

How would you feel? Vague? Confused? Frustrated? Abandoned? All of the above? Something else?

Well, I, myself, have been put into this situation more times than I care to admit. It’s one of the most frustrating job situations I’ve ever been thrust into.

What, exactly, constitutes “see if it works”? I could simply start the application, see if it starts, and say, “okay, it works.” I suspect that that’s not what the people who make the request are looking for. Yet time and again, I get a request from a developer or a designer to test something, and that’s the only instruction I’m given.

And it’s frustrating like you wouldn’t believe.

What’s even more frustrating is when (not if) the application comes back with some kind of problem, and the people who asked you to test come back with, “you said you tested this! Why is this broken?”

Want to know why there’s so much friction between developers and QA personnel? This is a likely reason. This is something that definitely falls under my list of documentation pet peeves.

The fact is, if you develop a product, and you need to test it for functionality, you need to specify what it is you’re looking to test. You need to define — and spell out — what constitutes a “working product” from one that’s “defective.” Just because a car starts doesn’t mean it’s working. You still need to put it in gear, drive it, steer it, and make sure that it can stop.

If you are creating a product, you need to describe what parameters are required for it to pass testing. If you’re asking someone in quality control to test your product, provide the tester with guidelines as to what should be checked to ensure the product is functional. Better, provide him or her with a checklist to determine whether or not your product can be released. If you discover additional items that need to be tested, then update the checklist.

(If you want to know more about checklists, I highly recommend The Checklist Manifesto by Atul Gawande. It’s actually a surprisingly excellent read.)

So any time you release a product for testing, tell the testers what it is that constitutes a “good” product. Don’t just send it off with vague instructions to “make sure it works” and expect it to be tested. More often that not, that will result in a failed product — and defeat the entire purpose of why you’re looking to test it in the first place.