Notes are not documentation

Since I speak frequently at SQL Saturday, much of my audience is usually made up of data professionals. So whenever I do my presentation about technical writing or talking to non-technical people, I always ask the following question: do you understand the difference between data and information?

For those of you who don’t understand what I’m saying, let me elaborate. The terms data and information are not, I repeat, not interchangeable. Data refers to the collection of statistics, facts, and figures that are gathered through observation, research, and log captures. Information, on the other hand, is an interpretation of that data. Its creation involves analyzing the data, interpreting it, drawing conclusions from it, and presenting it in a way that can be understood by others. To put it another way, data refers to the raw materials, while information is the “finished” product.

(We could also get into a discussion that talks about how bias is introduced when data is analyzed and interpreted by humans, all of whom have some measure of preconceived bias, no matter how small, about the data they’re researching, but it goes beyond the scope of this article, and I won’t get into that now. That is another topic for another day.)

Once I establish that distinction, that’s when I go into what I believe is an important point about written communication: there is a difference between notes and documentation.

I believe this distinction is critical, and is often overlooked by people trying to write documentation. (One of the biggest things that disparaged one of my previous employers was that they did not understand — or worse, did not care about — that difference.) How many times have you been frustrated whenever you’ve asked for documentation about something, and the person you asked pointed you to something like a loose collection of seemingly-meaningless and disorganized scribbled notes that are kept in a three-ring binder? (Okay, maybe they’re kept digitally these days, not in a binder, but humor me, here.)

Granted, notes are important. They are thoughts in someone’s head that are expressed in written form. They are often important concepts that are jotted down so they can be remembered later. Those notes can come in many forms. How many of the best ideas, for example, started out as notes scribbled on a cocktail napkin?

However, more often than not, notes are only meaningful to the person who wrote them. Notes are mnemonics. They are not conveying information to a wide audience. In all likelihood, most people who read notes will not understand what they mean. Only the person writing the notes (or, if they’re jotted down during a meeting, the people attending the meeting) will understand what the notes are.

Documentation, however, is an interpretation of those notes. Documentation is notes that are presented in a way so that they can be understood by a wider audience. This is what professional communicators, such as technical writers, do. They’re in the business of taking loose data, such as notes, and making it meaningful.

Let me say it again for emphasis: notes are not documentation. To go back to my data and information analogy, data is to information what notes are to documentation. Notes are the raw material, but documentation is what makes the notes meaningful.

Ghostwriting — the art of writing for someone else

One of the new projects I’ve taken on is ghostwriting ‘blog articles for one of my clients. While I have plenty of technical writing experience — where I take a topic or application that isn’t mine and try to write about it — ghostwriting is an entirely new experience for me. Not only is it something new for me to tackle, I’m finding the experience to be interesting, and even fun!

My client maintains a ‘blog as part of his website, and by his own admission, isn’t a prolific writer — which is where I (along with one or two others) come in. I’ve only done a couple of articles for my client so far, but I’m learning a few things as I go along.

  • Keep in mind that it isn’t your article. One thing I need to remember is that even though I’m the one doing the writing, I’m not the one doing the “writing.” Essentially, I’m taking someone else’s thoughts and putting them into an article. (Sounds a lot like technical writing, no?) While I’m putting these thoughts and ideas into words, they are not my thoughts. The intellectual property belongs to my client, not me. As such, I consider the article as being my client’s property.

    I recognize that this can be a potentially slippery slope; by that same token, it could be argued that technical writing could belong to the subject matter expert (SME), not the person writing the documentation. I won’t talk about that here; first, this goes beyond my expertise (maybe someone who knows more about intellectual property law than I do can address this better than I can), and second, this discussion goes beyond the scope of this article.

    As far as I’m concerned, the client has the final say about the article. It’s possible that my client might give me credit for writing it, but that’s up to him. I’m just taking his thoughts and putting them into words.

    Speaking of writing someone else’s thoughts…
  • Writing what someone else is thinking is hard to do! Most people understand how difficult it is to understand another person’s thoughts; after all, that’s what communication is all about. I’m sure most communication professionals are familiar with the Shannon-Weaver communication model. For the benefit of those who aren’t, here’s a quick synopsis: a sender sends a message to a receiver. However, noise breaks down the transmission (note: the noise may not be literally “noise”), so when the receiver receives the message, it is never 100% accurate (and it never will be; the noise is always there. It’s like a mathematical graph; the line approaches, but will never reach, 100%). The receiver sends feedback to the sender (during feedback, the sender and receiver roles are reversed — the feedback becomes the new message), who uses it to adjust the message, and the cycle begins again.

    That communication model becomes magnified when ghostwriting an article because what the receiver — in this case, the ghostwriter — is feeding back to the sender is much, much more precise. A ghostwriter is trying to write on behalf of the client, and the client wants to make sure that what is being written is (1) accurate, and (2) maintains a voice that the client likes. In all likelihood, the client and the ghostwriter will go through several iterations of edits and adjustments.

    This reminds me of another thought…
  • I fully expect that what I write will be changed. Never get too attached to anything that you’re ghostwriting. Any time that I ghostwrite a work, I fully expect it to be different by the time my client and I are finished with it. As adjustments are made between me and my client, what we end up producing may look completely different from what I originally wrote.
  • You’re writing for someone else — but still be yourself. Even though I’m writing someone else’s thoughts, I never think about whether or not my writing “sounds” like the person for whom I’m writing. Thinking about writing in another person’s voice stifles my work and is a huge distraction that destroys my productivity. I write whatever comes naturally to me, and only through the editing process do I start worrying about the article’s voice, when the client starts adjusting the article to his or her liking.

    This thought brings to mind a quote from one of my favorite movies.

“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 (played by Sean Connery), Finding Forrester
  • I’m learning new things! I’ve written before that one of the best ways to learn something is to write about it. Any time that you write about a topic, you end up learning about that topic — sometimes to the point of becoming an SME! Ghostwriting is no different. As I’m writing for my client, I’m learning new things and gaining new perspectives that hadn’t previously occurred to me.
  • I’m gaining new writing experience. I think this might be one of the biggest benefits of ghostwriting. Not only am I gaining additional writing experience, I’m also learning how to do so from another person’s viewpoint. As I mention above, I’m learning new things. I’m also learning how to be a better communicator, as it sharpens my communication skills as I continually feed back with my client. And it also teaches me how to look at things from a different point of view, which is what ghostwriting forces me to do.

I’m discovering that ghostwriting is a rewarding experience. It’s a great way to gain writing experience, and it ultimately makes me a better writer, a better worker, and a better person.

Communication lessons from air disasters

I’ve always had a morbid fascination for air disasters.  (Don’t ask me why; I have no idea.)  I’m fascinated by shows such as Air Disasters, Why Planes Crash,  and Mayday: Air Disasters.  Whenever I hear about a plane going down, I’ll start thinking about what happened, clues, what might have caused it, and so on.  There are times when I think I should have gotten a job with the NTSB.

Greg Moore has some publications in which he talks about lessons learned from aircraft accidents; his book partially discusses these lessons.  He also has an excellent SQL Saturday presentation titled “Who’s Flying The Plane?” which talks about lessons learned from air disasters and how they can apply to IT.  Go check it out if you have a chance; Greg gives a great presentation!

For the purposes of this article, however, I want to concentrate on a particular topic: how communication — or, the lack of — either contributed to or was the root cause of a disaster.

Last night, I watched an episode of Air Disasters that talked about the plane crash that took the life of professional golfer Payne Stewart. The plane went down after the cabin depressurized (the cause of which was never determined), the crew became incapacitated, and the plane ran out of fuel. What made it interesting to me was that bad documentation might have been one of the contributing factors to the accident. After the cabin lost pressure, the crew likely consulted a checklist, as is standard procedure for nearly any cockpit activity or incident. The checklist was poorly written and unclear. What should have been the very first instruction was, “put on your oxygen mask.” It was not. By the time the crew got to that instruction, it was too late; they were overcome by hypoxia.

It reminded me of a tenet that I preach in my documentation presentation: if, in a step-by-step instruction, an instruction cannot be understood within a few seconds, it has failed.

I also remember another Air Disasters episode that focused on Avianca Flight 52.  In January of 1990, the plane, a Boeing 707 carrying 158 people, crashed on approach to Kennedy Airport in New York after running out of fuel, killing 73 people.  There were numerous communication issues during the flight.  Had any one of them been addressed, chances are the disaster never would have occurred.

How often have you been involved in some kind of activity where things were miscommunicated?  How well did those activities go?  I’m guessing that they didn’t go well.  How often have they happened when deadlines were approaching?  What was the mood of your organization?  I’ll guess that it was likely one of high stress and low morale.  And during that time, how smoothly did things go?  Probably not very.  I’ll bet that plenty of mistakes were made.

I’m painting this picture within a business environment.  Imagine what these conditions are like when people’s lives are at stake.

The number of disasters that have occurred from poor communication are countless; entire studies have been dedicated to the subject.  Indeed, numerous solutions and subcategories related to miscommunication have been devised.  The airline industry developed the process of crew resource management.  Extensive research has been done on the phenomenon known as groupthinkEven simple measures such as checklists have been studied and implemented.

The moral of the story: good communication, including documentation, is critical. The consequences of it can have adverse effects. At best, bad communication can disrupt your business. At worst, it can cost lives.

Rethinking my resume

I learned something new today. But first, here’s a little background behind it.

Let me start by saying that I resent that job searches these days are performed much more by machines than humans. During times when I’m employed, I get irritated by emails resulting from bots that do keyword searches on my resume and constantly spam me with job inquiries for which I have no interest. Likewise, I also make no secret that I hate spam recruiters.

That said, now that I’m not currently employed and I am job hunting, as much as I hate robotic resume scans (and believe me, I still do), it’s the nature of the beast. If I want to get my resume seen by the right people, I need to be able to play the game.

Whenever I’ve updated my resume, I’ve always written it thinking that a human will look at it. These days, I need to design it with the mindset that a machine will look at it.

I was struck with that realization today. One of my networking contacts connected me with a career counselor. We spoke for about fifteen minutes over the phone this afternoon. He encouraged me to send him my resume for a review. I sent it to him, feeling confident that it would be well-received. But when he replied back, he hit me with a dose of reality.

First, he told me that my resume was not ATS (applicant tracking system) compliant (a brand-new term for me). He gave me some tips for redesigning it. Additionally, I searched Google for ATS compliant Word templates, and found this site, which includes a link to free templates. As soon as I find one I like, I intend to use it to redo my resume.

Additionally, I’ve noticed that a lot of online applications ask me to upload my resume, and when I do, it parses it into their system. And more often than not, it does not parse it correctly, which frustrates me. It did not occur to me that redesigning my resume not only makes it better to parse, it also makes it easier for potential employers to find. This may have been sabotaging my job search, and I wasn’t even aware of it.

Second, he also informed me that I had overused the word “professional” — something else that had escaped my attention. It’s the equivalent of saying “um” when you’re doing a presentation — you’re not aware you’re doing it (and I probably do when I do my SQL Saturday presentations) until someone else points it out.

Little pieces of advice like this will help my job search — and hopefully, I just improved yours, too. I’ve practically made a career out of adapting to my environment, and I realized today that that includes my job search. No, I still don’t like that my resume is searched by machine. But that’s the nature of the game these days, and if I want to succeed, I have to play it, whether I like it or not.

Modern technology requires modern documentation

While I was perusing Indeed.com, I came across a job listing that included these two paragraphs. (The bold type is my own add for emphasis.)

Responsible for technical writing/editing for all types of documentation produced within a modern software development environment.

Strong knowledge of word processing software, strong writing and analytical skills to document software capabilities

As soon as I saw it, this Dilbert cartoon immediately popped into my head.

Tina the Tech Writer is absolutely correct. Technical writing is not word processing. The two terms are not interchangeable. But there are too many ignorant people out there who think they are. Too many people still think technical writing is either just glorified administrative assistant work, or is something that can get thrown together in just ten minutes. It’s my number one professional pet peeve. And it’s a major reason why I preach the gospel that I do at SQL Saturday.

Technical writing and communication is more than just writing documents and manuals. It’s about presenting data and information. It’s about online help. It’s about design and UX/UI. It’s about life cycles (I’ll say it again: there is such a thing as a document development life cycle). It’s about knowing your audience, readability, understanding document structure, developing the right kind of document for the situation, and so on, and so on, and so on. I could keep going (but I won’t).

How often do you look up a paper document for instructions anymore? These days, it’s mostly PDFs, web pages, and online help. Granted, books and hardcopy still have their place, but these days, a lot (if not most) people turn to other resources for their information. Technical writing is about supplying that information, using whatever means necessary.

It is not word processing.

By the way, in case you’re wondering, no, I did not apply to the job.

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.

Coming up with ‘blog article ideas

Ever come up with a great topic about which to write an article? Do you have something on your mind that you want to get out of your system? Did you just learn something new and profound? Or is there some topic about which you don’t know but are trying to learn? Did you pick up some useful tidbit that you want to set aside for later use? Did you come across something you want to share?

I could keep going with this, but I’d rather not write a rambling paragraph that will eventually bore you; besides, I think you have the idea. I’d guess that one of the most common questions when trying to write a ‘blog is, “what do I write about?”

For me, personally, a lot of my ideas just pop into my head (including for this very article that you’re reading right now). If I think the idea is profound enough that it might help other people, I’ll start writing about it. Other times, I’ll come up with some idea, jot it down in a post, and save it for later. I have 100+ such draft articles; whether or not they ever see the light of day remains to be seen.

There are a number of things to consider when coming up with draft article ideas (and I dedicate several slides to this very topic in my ‘blogging presentation). If you’re trying to come up with things to write about, here are some thoughts that might help get you going.

  • What’s on my mind? It might sound obvious, but a lot of my ‘blog article ideas come from random thoughts that just happen to pop into my head. They’ll come from random sources — something I’m working on, something I’m watching, reading, or listening to, a question that someone asks, and so on. Every now and then, they’re thoughts that I think might help someone out. That can make great article fodder, so make sure you at least make a note of it. It happens more often that you might think; I’ve surprised myself at the number of ‘blog articles I’ve written that started as just random thoughts in my head.
  • I know something you don’t know — and I’m willing to share! Chris Bell, one of my friends on the SQL Saturday speakers circuit, once told me something profound, and it’s something I haven’t forgotten. He said, “an expert is someone who knows something that you don’t.”

    I’ve been a working professional for a long time now (I won’t say how long!), and I’ve learned a lot in my experience. I think I have some knowledge in at least a few subjects, and what I think can potentially help other people. Helping other people is one of my great passions, and if something that I know helps someone else, then I’ve accomplished something.
  • I just learned something new! Some people seem to have a misconception that you need to be an expert at something to write a ‘blog. Wrong! If you’re learning something new, keeping an online journal about what you learn is one of the best reasons to maintain a ‘blog! You’ll be able to see for yourself just how much you learn. Additionally, if you’re actively seeking new employment, it shows potential employers that you’re learning something, and that you have the ability to learn. Not only that, it shows off your expertise in terms of what you’ve learned. That’s something that hiring managers like to see!
  • I don’t want to forget this. Let me write it down. One of those people you could help is yourself. Matt Cushing tells a story in his networking presentation about the time he was trying to solve a problem, and he found the answer to it… in his own ‘blog! He had written an article about the very thing he was trying to solve, and found the answer in his article that he had forgotten about!

    As Matt says in his presentation, “a ‘blog can serve as your own personal Google.” A ‘blog can serve as scratch notes to yourself, and it might even help others in the process.
  • Bring people in. Don’t drive them away. You want people to read your ‘blog, don’t you? Like anyone else, I have thoughts and opinions about a lot of things, but I won’t ‘blog about a lot of them. I generally avoid any topic that’s divisive. You will almost never, if ever, see me discuss politics or religion on my ‘blog (I despise talking about politics, anyway). If I want to talk about religion, I’ll go to church. If I want to learn about politics, I’ll read The New York Times. Unless your ‘blog is specifically about those hot-button topics, they are more likely to drive people away than bring them in. I will not touch them on my ‘blog.
  • Avoid posting anything that is overly-sensitive or qualifies as “TMI,” unless it’s relevant to your topic. People generally don’t want to hear about your last trip to your gastroenterologist. Stuff like that isn’t typically what ‘bloggers write about. However, if some anecdote comes out of it — “my appointment taught me a lesson that applies to my professional life,” for example — maybe then, it’d be appropriate to write about it. However, be careful about it — make sure that what you write is appropriate for your audience. Nobody wants to read the details of your last trip to the bathroom while you had the bad case of diarrhea.
  • It’s okay to go off-topic once in a while. At the time of this article, Steve Jones of SSC is taking a sabbatical from his job (a nice little perk that he has available to him). During his time away from work, he has been ‘blogging about his daily exploits, which include skiing, learning to play guitar, and working around his ranch. I’ve been enjoying his posts, and I even told him that I was living vicariously through his posts.

    I’ll occasionally post an article that has nothing to do with my job, technical communication, or professional development. I’ll sometimes write about my extracurricular activities — my music endeavors (I play four different instruments), my workouts (I am an active Crossfitter), and so on. If you maintain a ‘blog about professional topics, it’s okay to post something off-topic now and then. It shows you have other interests, and it shows that you have a life outside of work. It shows that you’re human.

There are numerous other ways to generate ideas for ‘blog fodder. Feel free to comment below with your favorites. Hopefully, these thoughts are enough to help you get your own ‘blog going.

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