Heading graphics: it’s not just about good looks

I’ve been building Confluence pages as my initial projects for my (still-relatively) new employer. I’ve been building landing pages, coming up with designs and layouts as I go along.

For a couple of these pages, I wanted to come up with graphics — not just to be aesthetically pleasing, but also to give each page an identity. That way, someone visiting them can quickly and easily discern that that’s the employee resources page, or the architecture team page, or whatever page it is.

I’ve said before — and this is something that I preach as a technical communicator — that reading is work. It takes effort to read a piece of text and to comprehend it. If I’m writing a step-by-step guide, my rule of thumb is, if a step takes longer than a few seconds to understand, it has failed and must be rewritten.

Have you ever read a long piece of text (that isn’t a book you’re reading for fun) and realized how mentally tired you felt after reading it? For that matter, do you even want to read such a long piece of text? There’s a reason why people never read terms and conditions that come with applications. Take a look at all that black text, and tell me if you really want to read through it.

On that same note, it’s been often said — and it’s true — that a picture is worth a thousand words. A graphic will often convey information that’s often difficult to put into words.

Some logos are so recognizable that they are iconic: Apple, Coca Cola, Nike, Amazon, and the list goes on. If you come across a web page with one of these logos, you’ll almost instantly recognize what the page is about.

Even when I write these ‘blog articles, I try to choose graphics that are illustrative of what I’m writing.

That’s what I’m after with these Confluence pages that I’m building (they’re internal to the company, so I’m somewhat hesitant about showing them off). An employee can take a quick look at the page and know that (s)he is in the right place.

Granted, heading graphics aren’t always appropriate for every document (resumes, anyone?). However, if they’re used effectively, they can add a lot to a document and maybe even make it easier to read. Good graphics aren’t always about making something pretty; it can sometimes, in and of itself, convey a message.

Improvement through rewriting

If you’re an application developer (or at least you used to be one, like me), how many times have you come across an old piece of code that you wrote and said to yourself, “what the f*%k was I thinking?!?” You say to yourself, I can write that much better now than I did back then, and your instinct is go back and change everything that you’d previously written.

The same holds true for documentation. I recently had an experience that reminded me of that.

I was updating my slide deck for my upcoming SQL Saturday talk this Saturday. I thought my slides were in pretty good shape, but I wanted to go through them to ensure that everything was still fresh and up-to-date. Besides, the organizers at SQL/Data Saturday LA sent me a link to their PowerPoint template, and I figured that I should use it for my slide deck for Saturday.

Indeed, when I went through my slide deck, I was hit with a case of “what the hell was I thinking?” Many of my statements and references were outdated. I found that I could rewrite much of what I’d originally written, making them more efficient and readable. Some items were unnecessary, and I eliminated them altogether.

I spent a couple of days rewriting my slides. When I was finished, I discovered that I liked the new slides much better than my old ones. I took the new slides and made some minor modifications (mainly removing the SQL Saturday LA branding so that it was more generic). If you’d like to see them, you can download them from my Presentations page.

So the moral of the story is, no matter how good you think something is, it can always be better. Don’t be afraid to review and edit something you’ve created. You might find that you like your new version even better.

(P.S. check out my presentation this Saturday!)

I’ve landed!

After 388 days, 557 submitted resumes, and countless rejections, I’m happy to report that I have landed!

I have accepted a position for Insight Global. I will be working remotely as a technical writer for their client, PlutoTV! I start my new gig in a few weeks, depending on how long it will take for them to configure and send me my new work laptop!

I have made no secret about how stressful this job search has been, and I even talk about it in my job hunt presentation. Indeed, an entire calendar year is a long time to be without gainful employment, and it is the longest that I have ever gone without regular work. But I persevered and survived it, and I’m very much looking forward to this new opportunity!

Thanks to all of you who have followed my exploits and supported me!

The Value of Paper vs Convenience of Digital

I wrote a while back that, while digital documentation dominates the world today, paper isn’t necessarily dead. That said, my friend, Greg Moore, notes an issue with printed material that didn’t occur to me, and it has to do with data security. Read on for more.

greenmountainsoftware

About 35 years ago in the fall, a housemate of mine got a phone call, “hey, I’m a caver who’s passing through your area this weekend and found your name in the NSS Members’ Manual, I was hoping maybe you could hook me up with a caving trip.” Well it just so turns out that the RPI Outing Club traditionally does Friday night caving. (Why night you might ask? Well it’s always dark in the caves, so going at night leaves time on Saturday and Sunday to hike, rock-climbing, canoe, etc.) My housemate invited the guy along and he joined us caving (I think in Knox Cave).

I mention this story because it’s an example of how the NSS Members’ Manual has often been used over the years. Talk to enough old-time caves (especially those who recognize the smell of carbide in the morning) and many will mention how they’ve…

View original post 1,404 more words

What’s your (tag)line?

Let’s say you’re an ad exec making a commercial. You’ve been tasked with coming up with a great tagline (and maybe a slogan) for a product. What would it be?

Or, to get to the point of this article — I mentioned earlier about marketing yourself. What would your tagline be?

For me, personally, it’s taken many years, but I think I’ve finally figured mine out: “My job is to make other people’s jobs easier.”

Let’s back up a bit. How did we get here?

There have been many great taglines in the history of advertising. Whenever you hear one of these, a specific product immediately comes to mind.

  • Think Different
  • Just Do It
  • Got Milk?
  • America Runs On Dunkin’

Each of these taglines immediately invokes the product they represent: Apple, Nike, California Milk Processor Board (and eventually, the entire dairy industry), and Dunkin’ Donuts.

Through my past several months of job hunting, it occurred to me that my career could best be summed up by what I did at one of my previous jobs. When I worked for a server infrastructure department, my job was to provide information to the server team in order for them to efficiently do their jobs. The department was a support team. My job was to support the support team.

It occurred to me that that was a good summary of my career, and a description of what I do best. I’m passionate about supplying my coworkers with whatever accurate information they need to do what they need to do, usually through documentation (although I use other means as well — it’s good to have database experience). This has created a mindset, as well as a degree of assertiveness, whenever I go into interviews.

So, my tagline is, “My job is to make other people’s jobs easier.”

What’s yours?

Reinventing the #resume (again) #JobHunt

I had a conversation today with a recruiter — technically, it was an interview, but the way we spoke, it was more of a conversation between an agent (her) and a client (me) — who gave me some advice regarding my resume. I came away from the conversation with a few insights, and I’d like to share those insights here. This is not the first time I’ve written about resumes. I continually learn something new about them.

We left the conversation with her giving me a homework assignment: revamp my resume to incorporate what we had discussed.

Probably the biggest takeaway was to rethink how I was presenting my resume. I shouldn’t have the mindset of a job seeker telling prospective employers to hire me. Rather, I needed to approach it as a marketer. I’m marketing a product. The product I’m marketing is me.

This mindset is important. When you’re trying to present yourself to an employer, you feel a need to impress them with your extensive experience, everything you’ve done, and the many reasons why the employer should hire you. But if you’re marketing yourself, the thought process shifts. Instead, you’re advertising yourself and your skills. “Hire me! Here’s why!” She told me that it’s okay to not put everything on your resume — not lie, mind you, but rather, not throw in the kitchen sink when putting your resume together. Just highlight the important selling points. If they want to know more, they can refer to your LinkedIn profile — and maybe even call you in for an interview (which, of course, is the purpose of a resume).

I found this to be profound, because this is a point that I espouse as a technical writer, and yet I don’t practice what I preach when it comes to my resume. I am a believer in not necessarily including everything on a document. And yet it never occurred to me to apply my own technical writing skills to my own resume. Don’t try to provide every little detail. If they’re interested, they’ll ask for more (and if they want more, they can look at my LinkedIn profile).

I mentioned ageism as a concern, and a possible reason as to why I haven’t had a job nibble in seven months. (I believe ageism exists in the job hunt; it is illegal, but is nearly impossible to prove.) In the same vein of not needing to include everything, one of the takeaways was to only list positions for the past ten or so years. One of my concerns was that my experience before 2009 would likely reveal my age, but at the same time, it was all professionally relevant, and I didn’t want to leave it off. She suggested an idea that had never occurred to me: list the jobs (employer and title), but leave off the dates. Just say “here’s where I worked before 2009.” Again, if an employer wants to know more about those positions, check out my LinkedIn.

As an afterthought, after I’d removed the dates from the older positions, I still had a potential age identifier on my resume: my educational experience included my dates of graduation. Sure enough, in my latest resume revamp, my graduation dates will be removed. Employers just need to know I have a Masters degree; they don’t have to know when I got it.

The recruiter also asked me another question: what accomplishment at each position are you proudest of? I have to admit that that was a good question. She said that it was a question that should be asked for every listed position, and the answer for each was something that should be included on the resume.

I was told, be your own client. Market yourself. When it comes to marketing yourself, you’re your own blind spot. Only when it was pointed out to me did I know that the blind spot was even there.

Bad web forms — how to drive people away from your site

I’ve come across my share of bad design, and I’m sure you have as well. I’ve especially come across some egregious examples as a job applicant.

I came across one that particularly set me off. While poking around Indeed, I found a technical writer position for GitLab that interested me. Of course, most people who work in IT are familiar with GitLab, so they have a reputation. I read through the description, and it sounded interesting, so I clicked the button to “apply on company site.”

The subsequent link took me to this page.

The page talks about the technical writer roles and responsibilities. It talks about the hiring process, it includes a salary calculator, and it even talks about benefits, including stock options.

Nowhere on the page was there any link to actually apply for the position!!!

If you don’t believe me, check out the link and see for yourself. No wonder why they need technical writers. I understand and appreciate GitHub’s reputation in the IT community, but this page is seriously making me question whether or not I really want to work for them.

GitHub is far from being the only offender. I came across another page that, even after they asked me to upload my resume, it still asked me to manually input my work experience. (Even worse, these were required fields; there was no way around this. What if you’re a student with no work experience?) After I hit Submit, it came back and told me there were errors. It had cleared out all the dates I’d entered (I had entered months and years), and it insisted that I entered days. Seriously, raise your hand if you actually remember what day you started or ended a job from years ago. I have enough trouble just remembering the month or year. It made me question how well their automated formatting really worked (if it worked at all). Once I filled those in (with the best guesses for days), it told me there was another error. I clicked the message, expecting it to show me where the error was. Nope. It just told me there was an error. I had to search the entire page to figure out what it was complaining about.

I’ve come across too many forms like this during my job hunt. I also remember coming across some very badly designed forms years ago from previous job hunts — some that were so badly designed that they discouraged me from applying for the jobs.

I’ve talked about making documentation easier for the end user, and this is far from the only article I’ve written about how bad design is a detriment to anyone who needs to follow instructions. UX/UI needs to be as painless as possible for the end user. If you’re a vendor, bad design can drive away customers. If you’re an employer, you run the risk of discouraging qualified applicants.

Like good documentation, good form design needs to be well-thought-out and well-designed. Don’t be the organization that lost customers because your forms were too arduous to use.

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.