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

SQL Saturday NYC — a quick debrief #SQLSat912 #SQLSatNYC #SQLSaturday

I wanted to take a quick moment to do a quick debrief of the events from this weekend. I’m actually working on a longer article about the events of this weekend, but it’s still a work in progress. Hopefully, I’ll get it out later this week!

Until I get that article cranked out, here are a few highlights from SQL Saturday #912, New York City.

  • As I mentioned, I gave three presentations on Saturday, which is a new record for me. I started the day with my networking presentation. I felt it went well, but there was one disappointment: only two people showed up. Granted, I believe that I should always put on a good performance, no matter how many people are in your audience, but my networking session is more effective with a larger crowd, especially since I have a section in my presentation where my audience actually networks!
  • I did discover, to my chagrin, that my presentation clicker was missing the USB plug, rendering it useless. This was also disappointing — it was effectively a brand-new clicker, only used once, and I paid $40 for it. It occurred to me later that I think I know where I left it. I think I left it sitting in the desktop PC I used for my presentation in Providence. I don’t think I’m getting it back. Looks like I’ll have to invest in a new clicker.
  • I sat in on Matt’s session (again!), which was right after mine. His presentation keeps getting better every time I see it. It also occurred to me that both of our networking presentations complement each other very well, and I would love it if we could present back-to-back more often. We both bring different perspectives to the same topic, and the two of us combine for a very effective presentation!

    I felt bad for Matt, because, like myself, he also had a small audience (only four people, including myself). He gives a great presentation, and he deserves a larger audience.

    I also had to leave his session early, because I had to go to…
  • my second presentation of the day. This one was better attended — ten people showed up. This room setup was more like a conference room, which allowed me to give my presentation while seated. This meant I didn’t have to use my presentation clicker.
  • I ran into Thomas Grohser during lunch — my friend, one of the co-organizers of SQL Saturday #912, and the man who scheduled me for three presentations. He said to me, “go get your lunch. You’re going to need it!”
  • My third and last session wasn’t until 4:45. I thought about attending other sessions, but lack of sleep was catching up with me (I’ll talk about it more in my other article). I decided to pass on the next two session slots in favor of getting myself some rest.
  • My third session was held in the same room as my previous session, so again, I didn’t need my clicker. There were around six people in the audience when I started, but people filed in as I went along. I think there were around ten when I finished.
  • Amusing moment at the end of the day: I sat in the front row for the raffle prize drawings. James Phillips, another of the co-organizers, was doing the wrap-up, and he let me pick one of the raffle tickets. I reached into the bowl, mixed the tickets, and pulled out… my own ticket!

    I won a Bluetooth speaker!

So overall, it was a fun day (as SQL Saturday usually is). There was a lot more to my weekend, but I’ll save those details for my other article, which is still a work-in-progress. You should be able to read that article later this week.

That should pretty much wind up my SQL Saturday schedule for this year! My next scheduled speaking engagement is in Seattle next month for PASS Summit! We’ll see you then!

Reminder: come hear me speak (x3) in NYC #SQLSat912 #SQLSaturday

Image result for times square nyc

This is a reminder that on Saturday, October 5 (a week from tomorrow, as I write this), I will be speaking at SQL Saturday #912 in New York City — not once, not twice, but three times!

I will be doing the following three presentations.

  • Tech Writing for Techies: A Primer — Documentation is a critical but disrespected process. Learn why tech writing is important and what your organization can do to encourage it.

SQL Saturday is always a good time, and the New York City event is one of my favorite ones to attend! Go to their site to register for the event, and come check out my presentations — three times!

The Whistle-Blower Knows How to Write

(Photo source: The New York Times)

By now, I’m sure many of you have heard all about the bombshell that has hit the American political establishment. Yes, I have my own political opinions as to what’s happening. But I won’t express them here. That is not why I am writing this article.

I felt compelled to write this after reading this article (whose title I shamelessly stole for this article) in the New York Times. The author, Jane Rosenzweig, is a college writing instructor. Rather than analyze the politics of the situation, she instead scrutinizes the whistle-blower’s writing itself. And what she says is exactly the reason why I preach what I do at SQL Saturday.

Go ahead and read Ms. Rosenzweig’s article. It’s a pretty good read.

I will admit to a couple of things: (1) I am a self-admitted grammar snob, and (2) I am not a grammatically perfect writer. I was never an English major, and I’m sure much of my writing would likely make many writing instructors cringe. I’m admittedly liberal with a number of grammar rules, such as ending sentences with a preposition (which I do from time to time). That said, I know the differences between “your” and “you’re” and “too,” “to,” and “two.” I am an unabashed and unashamed defender of the Oxford comma (on this, I have a very strong opinion; I believe not using it is incorrect). And I still believe that anyone who says “irregardless” should be strung up by his or her fingernails.

In any case, I do consider myself a fairly strong (though not perfect) writer. It’s why I have a job. And its importance is why I preach about the importance of communication. Communication is critical in any endeavor. You needn’t look further than the example put forth by the anonymous whistle-blower.

A picture is worth (writing) a thousand words

On a recent project in which I was documenting an application, I found myself hitting yet another case of technical writer’s block. I sat in front of the screen, staring at the application — sometimes, for hours — and came to the realization that all I was doing was blankly staring at the screen. I tried different techniques to stir up ideas as to how to tackle writing the documentation, but no matter what I tried, the words just wouldn’t come. Even just trying to figure out a document structure — never mind actually trying to describe the application — was proving to be elusive.

It was at that point where I decided to give up on trying to write a description of the application functions and turned my attention to grabbing screen captures. I went through the application’s menu structure, built a document heading hierarchy based on it, and started working on the application images I’d just captured. I took the time to clean up the images, including altering them to eliminate any client or user data (replacing them with “dummy” data), and formatting them for my document. Once I was satisfied with the result, I inserted it into the document, proceeded to the next screen capture, and repeated the process.

A funny thing happened during this process. First, I found that my document was expanding in content. Granted, it was mostly graphics, but it was, nonetheless, content. Second, I’m finding it easier to come up with ideas for descriptions and text content. Third, I’m no longer blankly staring at my screen; I’m finding that I’m actually productive. Finally, I’m finding myself having fun with the process!

This is not the first time that I’ve performed this process while writing a document. Indeed, I’ve often worked on documents in which I found myself in a writing rut, shifted gears to work on graphics, and discovered the spark that I needed to write the text.

It’s an age-old saying that “a picture is worth a thousand words.” Most often, this phrase is geared toward the perspective of the reader. However, what is not as appreciated is that this cliché is applicable to the document developer as well. If ever you find yourself in a writing rut, try working on the graphics. It might just be enough to spark ideas and get you out of the rut.

Stop treating technical writing like a second-class citizen

File this under another technical writing frustration.

Imagine that you are an application developer. You finish an app for a client that you send for review. The app is clearly labeled as a “testing version,” and includes source code (yes, I know this last part doesn’t happen, but just humor me for a bit). You are meticulous with your updates, keeping track of version control and changes. You ask the client to review it and get back to you. You move on to work on other projects, forgetting about the request. A few weeks later, you remember the project, and realize that you hadn’t heard from the client. You contact them to follow up, and are chagrined to learn that not only are they using your test version app in production, they also changed the source code for what they need.

Sounds outrageous, right?

Now, substitute the following words and phrases: “technical writer” for “application developer,” “document” for “app,” “draft” for “testing version,” and “MS Word” for “source code.” Welcome to my world.

This is an actual workplace scenario that happened to me a while back, and I was reminded of this recently when the same client asked me for an MS Word version of a document (that I had sent as a PDF — I was never, ever going to send them an MS Word doc again) so they could make changes. I refused, and I told them why.

The client in question had taken my Word document — the one that I had asked them to review — and I will add that I had DRAFT stamps all over it — and were using it in their production environment. Not only that, they had made changes to it for their purposes.

Well, I found and incorporated their changes, removed the DRAFT stamps (they were obviously okay with the document), and slapped a version number on it.

I also told myself that I was never sending them a Word document ever again. They were only getting PDFs from me.

I’ll be honest. What the client did absolutely pissed me off. By “changing the document for their needs,” they completely compromised and undermined my work, they blatantly stepped on my toes, and they completely disrespected what I do.

Most of the clients I work with aren’t like this, which is why I usually don’t have a problem sending a Word document (with DRAFT stamps) out for review. Thankfully, the scenario I just described is, in my environment, the exception, not the rule. Sadly, however, there are still too many people who hold this attitude that documentation is just a side item, and treat it like a second-class citizen.

This is one of the things that drives me to do SQL Saturday talks. This is why I do my presentations. This is why I rant about poor treatment of documentation. And this is why I actively tried to leave a job.

I’ve said this time and again. Document development needs to be treated in the same way as software development. The life cycle, including version control, is no different. Not doing so undermines what documentation is. It’s a critical function in application and professional development. And as someone who has had experience in both application and documentation development, I demand: stop treating documentation like a second-class citizen.

First drafts are ugly

“The secret to life is editing. Write that down. Okay, now cross it out.”

William Safire, 1990 Syracuse University commencement speech

“No thinking – that comes later. You must write your first draft with your heart. You rewrite with your head. The first key to writing is… to write, not to think!”

William Forrester (Sean Connery), Finding Forrester

“Just do it.”

Nike

I will confess that this article is a reminder to myself as much as anything else.

Raise your hand if you’re a writer, and whatever it is you’re writing has to be perfect the first time around. Yeah, me too.

How many times have you tried writing something, but in doing so, you hit a wall (a.k.a. writer’s block) because you don’t quite know how to put something in writing? Or how often have you written a first draft, only to take a second look at it a second time and say, “what a piece of s**t!”

(And speaking as someone with application development experience, this happens with writing code, too. Don’t think that this is limited to just documentation. This is yet another example of how technical writing and application development are related.)

Someone (I don’t know whom) once said, “one of the stupidest phrases ever coined is, ‘get it right the first time.’ It’s almost never done right the first time!” In all likelihood, you need to go through several iterations — review, editing, rewriting, etc. — before a draft is ready for public consumption. It’s called a “draft” for a reason.

The fact is, nobody has to see what you write the first time around. If you’re trying to get started on a document, just write what’s on your mind, and worry about making it look nice later.