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.

Advertisements

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.

Don’t tell me how to build the clock! Just tell me what time it is!

This article’s title comes from something that a former manager used to tell me all the time — often enough that he seemed very fond of saying it. Nevertheless, it’s an important message. This is not the first time I’ve written about this issue, but it’s something that occurs all too frequently. It is a problem in technical and business communication, and the issue is something that bears repeating.

I was reminded of this during our daily status update meeting this morning. The gist of this regularly scheduled meeting is that everyone has a short time — usually no more than a minute, if that — to provide a brief update of what they have going on. The key word here is brief.

One person proceeded to go into detail about some of the projects he had going (he has a tendency to do so). He’s been pretty good about keeping his updates short and to the point, but he wasn’t always like that. It took several long meetings and complaints to the manager to get him to tone it down.

For whatever reason, this morning, he reverted back to form. He started getting into details about his projects that, while important for the projects themselves, were unnecessary for status updates. It got to the point that I stopped listening to what he was saying and pretty much just zoned him out. I don’t know how long he took, but I’ll guess that he took three times longer than anyone else. Or at least it seemed that way.

This is something that everyone does (yes, I admit to doing it, too — ironically, even this very article may be too long). And it is a big problem in communication.

A part of the issue stems from human nature. We all have a limited attention span. The length of that attention span varies, but for the purposes of this discussion, let’s assume that it’s short — say, no more than a minute (sometimes, that might even be too long). If we’re communicating something, we need to make sure that it’s short and simple — and it had damn well better be efficient.

This is why people in roles such as technical, business, UX/UI, media, and marketing communication have jobs. They are in the business of taking large amounts of information and boiling it down into a format that most people can understand.

Whenever I’m writing a user or step-by-step guide, I follow a general rule of thumb: if an instruction cannot be understood within a few seconds, it has failed. That’s when I go back and rewrite the instruction.

Most of the time, people don’t want — or don’t need — or don’t care about — details. Unfortunately, too many people trying to communicate ideas don’t understand this (and worse, they often don’t care). As a result, horrible documentation (or, in some cases, absence of) is pervasive.

Too many people don’t understand that reading is work. It takes effort to read and comprehend documentation. One of my big pet peeves is any time someone tells me, “it’s right there in the documentation,” yet when I look at it, the information I need is buried someplace where I have to fight through the noise of other irrelevant text to find it.

This issue is the basic tenet of my presentation about talking the language of technology. People don’t want detail. They just want the information they need. If they need more information, they’ll look for it.

Good communication makes it easy for a recipient to quickly get whatever information (s)he needs. Don’t make someone have to work to understand communication. Don’t tell someone how to build a clock. Just say what time it is.

Don’t discount old documents

For those of you who have application development experience, how many times have you come across old code that you’d written and said to yourself, “what the F was I thinking?!?”

As someone with development experience, it’s happened to me more often than I can count. And as someone with tech writing experience, I can tell you that it applies to documentation as well.

As a technical writer, I’m often tasked with rewriting old documents that are out-of-date or no longer applicable. In the old days (i.e. before I knew better), I would essentially overwrite old documentation with the new, and often deleted the old. Now that I have more experience under my belt, I know now that that was the absolute worst practice that I could have done.

For starters, I used to have the mindset that the information in old documents was no longer relevant. The processes have changed, I used to tell myself. Why should I keep these documents around?

If you have this mindset, as I once did, I urge you to purge it. It is a poisonous attitude to have. As it turns out, old documents are extremely relevant, even if their information is out of date. Old documents are important for reference. I’ve often found myself referring back to previous versions when rewriting documentation.

I recently wound up a project that involved a rewrite of an application document. The application had been rebuilt from the ground up, and the documentation had to be rewritten to accommodate it. While documenting the testbed, I came across a number of functions that, with the limited testing dataset, didn’t seem to do anything. I went to the predecessor documentation and found what I was looking for.

Old documents are often also important in answering a simple question: why? As in, why was such-and-such process designed this way? What was this originally supposed to do? Why was this function changed? Many of these cannot be answered just by looking at application code; often, the answers are found in old documents.

These days, I make it a point to not overwrite old documentation. I back up old documents and either rename them or put them into an archive folder. I haven’t yet implemented a version control system to archive documents (we use Git in my office). If anyone makes use of version control systems such as Vault, Git, Subversion, or MS Azure DevOps (formerly TFS) to maintain documentation versions, feel free to mention it in the comments.

So if you are rewriting documentation, make sure you set aside the previous versions. You never know when you’ll need them again.

#SQLSaturday NYC — I’m speaking, I’m speaking, I’m speaking! #SQLSat912

Image result for manhattan skyline

The schedule for SQL Saturday #912 in New York City (Saturday, October 5) was released this morning, and I’m on it — not once, not twice, but three times!

I am scheduled to do the following three (!!!) presentations:

Looking at this schedule brings up a myriad of thoughts for me.

  • I don’t ever remember doing three presentations in a single day at any single event in my life. So I’m venturing into uncharted territory here!
  • Without fail, I absolutely love any SQL Saturday I attend! Also without fail, I am nearly always wiped out at the end of each one. I can only imagine how tired I’m going to be at the end of this one. At least I can sleep on the train ride home!
  • I purposely scheduled a late train home that night after the event so that I can get a decent dinner down in the City. I figure a couple of drinks during dinner might be in order that night!
  • My brother, who lives in Queens, has his birthday a few days before the event. I’m hoping to make it a birthday dinner for him that night!
  • To his credit, Thomas Grohser, who is one of the co-organizers for the event, emailed me asking if I was okay with doing three presentations. I sent him back a two-word reply: “challenge accepted!”
  • I was very happy to see that, as we requested, Matt Cushing and I have our networking sessions (titled Networking 101 and Networking 102, respectively) scheduled back-to-back! Go check out Matt’s session; it’s a good one!
  • If there’s any downside to doing three presentations, it’s that I likely won’t be able to attend other presentations that interest me. I do intend to attend Matt’s session (I need to keep my streak going, after all), and I’ll need to check the schedule to see what other sessions I want to attend (if I can).
  • Of all the SQL Saturdays I’ve ever attended, I’ve attended New York City the most often. For several years, including the first one I ever attended, I only attended NYC SQL Saturday. So for me, being chosen to selected to speak for NYC is special to me.
  • When I spoke here last year, I had an opportunity to get breakfast at Ellen’s Stardust Diner. It was right next to my hotel and right on my way to the Microsoft office (where SQL Saturday NYC is held). I managed to get there early enough to beat the tourist crowd. This year, I am once again staying in a nearby hotel (only a block away from where I stayed last year). I’m hoping to get there for breakfast again. Yes, I know it’s a tourist trap, but the singing wait staff is something else! You need to check it out at least once!

I can probably keep writing more thoughts, but at this point, work beckons! In any case, if you’re interested in attending NYC SQL Saturday on October 5, go to their web site and register for the event!

And come see me present — three times!

References and memorization

I was working on a document, and wanted to toggle the language on MS Word that was used for proofing (I downloaded the template from our UK subsidiary, so it was proofing in UK, not US, English). I couldn’t remember how to do it, so I consulted Google, found my answer, changed the setting, and went along my merry way.

For whatever reason, it got me thinking about Microsoft certification exams (it’s funny how one’s mind works sometimes). It’s been a long time since I took one. What got me thinking was that, when you take a certification exam, you are not allowed to bring any notes or references with you into the testing room (as far as I remember — I’m not sure if that’s still the case now; like I said, it’s been a long time since I took a certification exam).

In this day and age where finding information is as easy as picking up your smartphone, I really believe that memorization is overrated (and, maybe in some cases, even dangerous). I wrote as much a while back, and I still believe that now.

Back when I worked as an adjunct instructor, all my assignments, quizzes, and exams that I gave to students were open-book, open-note. I also told my students that they were allowed to help each other work toward the answers, including during an exam. They were not allowed to outright give each other answers; that constituted cheating and were grounds for failing the exam. Maybe some instructors might scoff at this approach, but my students were very good about adhering to those rules (many of them told me later that they learned more in my class than any other they’d ever taken), and there was a method to my madness.

For one thing, I told my students that the ability to look up and research information was an important skill to have. We, as imperfect human beings, are never going to remember absolutely everything, so to be able to know how find the correct answers is important. Second, when we’re in a working environment, the ability to work together as a team is critical. When you’re working within a team environment, being able to work with others to achieve a common goal is a big deal.

Finally, how many workplaces are going to tell you, “okay, put away all your books and references. You’re going to do this project entirely from memory.” I don’t know about you, but if a manager ever told me to do that, I wouldn’t be able to update and distribute my resume fast enough.

In his SQL Saturday presentation entitled “Why candidates fail the job interview in the first minute,” Thomas Grohser mentions that he does not expect any candidate to be able to know everything. If a candidate says that (s)he “does not know the answer, but here’s how I would go about finding the answer,” then that is a perfectly acceptable answer. More often than not, trying to do everything from memory is a bad and sometimes dangerous approach, and is a bad way of thinking.

We are not perfect. We will never remember everything. And anyone who says that (s)he knows everything is full of crap. Rather than try to brute-force memorize anything and everything, it’s more important to develop skills that teach you how to think and how to find, verify, and process information. If I was a hiring manager, that ability would be vastly more valuable than someone who says that (s)he “knows everything.”

Getting ready to speak at my first PASS Summit

I’m speaking at my very first PASS Summit this year!

I intend to ‘blog about my experience with my first PASS Summit. Hopefully, my exploits will help others who, like me, are also preparing for the first PASS Summit. This represents the first of those articles.

As I write this, PASS Summit is still four months away. Nevertheless, preparations are in full swing. My flight and AirBnB reservations for Seattle are already set. It’s been a while since I was last in Seattle (I think my last trip was in 2005). Seattle is one of my favorite west coast cities to visit, and I always look forward to trips out to the Pacific Northwest. My only regret about this trip is that baseball season will be over by then, so I won’t be able to catch a Mariners game while I’m there.

I do not intend to rent a car for this trip. To be honest, I’m becoming more and more paranoid about driving a car I don’t own in a metropolitan area with which I’m only vaguely familiar. I did rent a car for SQL Saturday in Washington, and driving around the Beltway was a harrowing experience; during that trip, I became very concerned about returning my rental car with a dent. So for PASS Summit, I intend to rely on public transportation; all my stops — Sea-Tac Airport, my AirBnB, and the Convention Center — are all along the light rail line. If I need a car, I’ll bum a ride off someone, or I’ll contact Uber or Lyft.

Prep work for the event itself on my end is also rolling as well. I’ve gotten emails from PASS about what I need to do to get ready. I’ve registered as a speaker, and I put my presentation into a new PowerPoint template supplied by PASS (and in doing so, I think I made my presentation even better — a lot of the changes will likely end up going into my regular slides). They’re supposed to review my slides, so I’m waiting for them to get back to me as to what changes (if any) I need to make. There are some things about my prep I’m not allowed to discuss — per PASS rules, I’m not allowed to discuss some things until they’ve announced it first — so, alas, I can’t talk about all my prep work.

Last night, I was at Ed Pollack‘s house, helping to prep for this weekend’s SQL Saturday. Knowing that Ed has experience speaking at PASS Summit (he’ll be speaking at his fourth this year), I asked him what I should expect. He told me to “expect at least one question that you can’t answer” during my presentation — maybe something impossible to answer, something I don’t know, or even something that has nothing to do with my presentation. He also told me that PASS Summit would be very busy — apparently there are many activities around PASS Summit that take place. I have friends and family either in or near Seattle; we’ll see how much of a chance I’ll have to get together with them.

I also figure that Matt Cushing‘s advice will likely come into play here. A good chunk of his presentation revolves around activities at PASS Summit. I guess I’ll find out in November how much of it comes into play!

Another thing on my mind is room setups. Although I’ve spoken at many SQL Saturdays, even the largest room in which I’ve spoken pales in comparison to the rooms at PASS Summit. I’m not necessarily nervous about speaking in front of a large crowd — I lost my sense of stage fright a long time ago — as much as I am curious as to how it’s going to work. It’s not something I’ll need to be concerned about until I’m closer to the date, but it is, nevertheless, something that’s on my mind.

I did a Google search for “what to expect at PASS Summit” and came across some interesting links. Some of those links are below (admittedly, I’m listing these for my own reference).

It’s still four months to PASS Summit, but a number of things are already in motion. I’ll be writing more about my experiences as we get closer to November!