It ain’t sexy, but it’s critical

Evacuated Highway 401 Color.jpg
(Photo credit: By Kenny Louie, CC BY 2.0, https://commons.wikimedia.org/w/index.php?curid=10535248)

Think, for a moment, about things that are never talked about — I don’t mean taboo topics, but rather, things that are boring, “ain’t sexy,” and so on — yet are absolutely critical if we want to maintain or move ahead our current standing. Off the top of my head, infrastructure and chores come to mind. Road construction, transportation infrastructure, and public utilities aren’t exactly exciting topics that are discussed over drinks, but maintaining them is absolutely critical if we want to keep our society moving. Likewise, nobody talks about housework, taking out the trash, fixing leaks, replacing appliances, and so forth, but it’s necessary if you want to maintain your home.

Documentation falls under this category. Let’s face it: the large majority of developers, analysts, and other business and technical professionals don’t enjoy writing documentation. Raise your hand if you’re passionate about documentation. (You, yes you, the technical writer in the back row, put your hand down. I’ll get to you in a moment.) But the fact is, documentation is absolutely critical if you want to keep your business afloat.

I was thinking about this not long ago, when I was describing aspects of my job to someone. I’m currently working on an important documentation project (a standard operating procedure document — SOP, for short), and I’ll admit that it isn’t the most exciting project. It isn’t unusual for me to zone out in the afternoon while I’m working on this thing. I was asked, is it an issue with your department or your company? I said no. It’s the nature of the beast. It would be like this regardless of where it was, whether it was with my current team, my current employer, or somewhere else.

No, working on the document is not exciting work. But it’s an important document that needs to be written. It’s a job that (almost) nobody wants. But it’s also a skill that I’m good at doing (or at least I like to think that I am). And it keeps me employed.

I’ve written before that documentation is one of the most disrespected technical tasks. But it’s a critical task if you want your business to stay afloat. You need to be able to pass information along to your colleagues, your employees, and your clients. Documentation is probably the best way to do it. So documentation needs to be clear, understandable, well-written, and presentable.

This is why I preach what I do at SQL Saturday. You ignore documentation at your own risk. No, documentation ain’t sexy. But it’s absolutely critical if you want to keep your business going.

How often should I ‘blog?

It seems like I haven’t been writing as many ‘blog articles as I’d like this month. There have been a number of reasons — among them, I’ve been sick, I’ve been busy, and so on, but that thought, in and of itself, got me thinking, and it actually gave me a ‘blog article idea. (It’s funny how ideas come about, sometimes.)

Last month, when I did my ‘blogging virtual presentation (if you missed it, you can view the recording of it here), I had a great question come up: how often should someone ‘blog?

To be honest, there really are no hard or fast rules as to how often you should ‘blog. I’ve known people who write maybe one article every few months. I know that Greg Moore tries to write an article each week. On the other hand, Steve Jones usually puts out at least two articles per day (when he’s not on sabbatical). For me, personally, I try to write at least one article each month, with a general target of ten articles a month. It doesn’t always happen; if you look at my archive (on the right side column of my ‘blog), you’ll notice that November and December of 2016 are skipped. That’s because I didn’t write anything those two months. By contrast, if you look at my article counts in 2019, I averaged a little over 13 articles each month. I guess 2019 was a good year for ‘blog articles.

There’s a balance to maintain when trying to be a prolific ‘blog article writer. For starters, there’s a matter of coming up with things to write about. A lot of ideas just come to me, but there are also times when we struggle to come up with ideas. Writer’s block is a common thing. There’s also a matter of finding time to write, and balancing it with other things in your life — work, family, activities, and so on. I’ll pretty much jot things down as soon as they come to me — as I’ve learned, any time I have an idea, I either take care of it right away, or write it down. And there’s nothing that says you have to write a complete article in one sitting; you can always jot your thoughts down and come back to it later. (Of course, sometimes, “later” might not be for a couple of years, by which time your idea has become irrelevant or obsolete.)

I’ve also noticed from my WordPress analytics that there seems to be a correlation between how many articles I write and how much traffic my ‘blog gets, which, of course, makes sense. If you don’t write anything, nobody will read what you (don’t) write. (Duh!) The more you write, the more people will read.

I’ll toss out a question that I ask in my ‘blogging presentation: what do you want to get out of your ‘blog? That will likely dictate how often you should ‘blog. But ultimately, how often you ‘blog is up to you. As Tom Lehrer once said, life is like a sewer. What you get out of it depends on what you put into it.

My ‘blogging presentation recording is online! @CASSUG_Albany @PASS_ProfDev

Were you interested in checking out my ‘blogging virtual presentation? Were you not able to attend?

Good news! A recording of my presentation is available online! Use this link to see my presentation on YouTube!

Blogging virtual presentation — Tuesday, January 21 @CASSUG_Albany @PASS_ProfDev

Today around noon (about an hour from now as I write this), I will be doing my virtual presentation about ‘blogging! Come and join me!

Welcome to Ray Kim's 'blog

On Tuesday, January 21, at noon (US Eastern Standard Time), I will be doing my presentation titled “Blogging for Success: Advancing your career by blogging.”

If you’re interested in starting a ‘blog, I’ll talk about my own experience with ‘blogging and lessons I’ve learned along the way. Some topics I’ll discuss include how I got started, ‘blogging platforms, and subject matter.

For more information and to register for the event, use this link.

Hope to see you there (so to speak)!

View original post

Blogging virtual presentation — Tuesday, January 21 @CASSUG_Albany @PASS_ProfDev

On Tuesday, January 21, at noon (US Eastern Standard Time), I will be doing my presentation titled “Blogging for Success: Advancing your career by blogging.”

If you’re interested in starting a ‘blog, I’ll talk about my own experience with ‘blogging and lessons I’ve learned along the way. Some topics I’ll discuss include how I got started, ‘blogging platforms, and subject matter.

For more information and to register for the event, use this link.

Hope to see you there (so to speak)!

Expect the Unexpected with DiRT

Steve‘s article reminded me about the first time I gave my Disaster Documents presentation at a SQL Saturday.

At the end of my presentation, one attendee started an argument with me. He kept saying that paper was dead, everything was online, and there was no reason to keep hardcopy documents. I argued, what if you can’t get to your online documentation?

Not surprisingly, he gave me a poor evaluation.

The bottom line is this: even documentation needs a backup. Other than, say, getting lost in a fire, paper documents can’t break. At a minimum, have hardcopy documents that instruct how to get minimal services back up and running, and back up other recovery documentation so you can recover it later.

Voice of the DBA

Disaster recovery is one of the core tasks that many DBAs think about on a regular basis. Ensuring that we can get our data back online, available, accessible, and intact is important. More than a few DBAs that haven’t been able to recover systems, find themselves seeking new employment.

That’s not to say that most DBAs perform perfectly under pressure. Plenty make mistakes, and there may be times when they can’t recover all data. There does seem to be a correlation between how often DBAs practice recovery skills and how well they perform in an actual emergency. I know that at a few companies, we scheduled regular disaster tests, though often with simulated recovery of a systems that didn’t expect to actually take over a workload. Arguably not a good test, but better than nothing.

Google takes things a step further. They have annual, company wide, multi-day DiRT (Disaster Recovery…

View original post 359 more words

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.