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!)

What a TV ballgame can teach us about design

This afternoon, the 2021 slate of spring training games started for Major League Baseball. And of course, being the big baseball fan that I am, I took to it like a lion to a steak.

I wasn’t thinking too much about design or layout until I heard Michael Kay of YES mention, “I think our fans will like the new clean design of our scorecard.”

At least that’s what I think he said. It threw me for a loop, because I am enough of a baseball fan that whenever I go to the ballpark, I’ll buy a scorecard and keep score during the game. So when he said “scorecard,” I thought about a pencil and paper in my hand (and, usually, a hot dog or a beer in the other). At that point, I realized that he was referring to the score display in the upper left-hand corner of my TV, as pictured below.

It then occurred to me: “wow! That’s a TON of information contained in that one graphic!” At that point, I felt compelled to write this article.

So, let’s break down just how much information is contained here. (A warning to those of you who don’t know anything about baseball: for most of this article, I am going to “speak baseball.” If you’re not a baseball fan, you’re just going to have to bear with me.)

First, I’ll start with a paragraph as to what information is contained in this graphic. Be forewarned: I am about to inundate you with information.

In the top of the third inning, Toronto leads New York, 3-0. There are runners on first and second, with nobody out. Jansen, the Blue Jays’ number 7 batter in the lineup, is facing Wojciechowski, the Yankee pitcher. Wojciecowski has thrown ten pitches, and has a full (three ball, two strike) count to Jansen.

That’s a lot of information to glean from a single graphic, isn’t it? Let’s break it down.

  • We’ll start with the score. Toronto 3, New York 0. (I’m sure that will please many Yankee haters out there.) The score dominates most of this graphic. I don’t want to say that’s obvious, but it does take up most of the image, and is the largest takeaway.
  • Underneath the score are two names, located under the teams for which they play: Jansen for Toronto, and Wojciechowski for New York. The 7 in front of Jansen represents his spot in the lineup (which would be a number from 1 to 9). “10 P” indicates that Wojciechowski has thrown ten pitches. (Note: since Wojciechowski is an unusually long name, the pitcher’s name and the number of pitches would not ordinarily run into each other like that.)

On the right side of the graphic, we see a couple of smaller graphics.

  • Let’s start with the box containing the shapes. We see three boxes, two of which are blue (and the third is gray), denoting baserunners on first and second base. The boxes represent the bases (going right to left, first, second, and third base). The boxes that are blue indicate that they are occupied by baserunners. If the bases were loaded, all three boxes would be blue; if no one was on base, all three would be gray.
  • Under the boxes representing the bases, there’s a “3” indicating the inning. The arrow (represented by the triangle next to the 3) denotes whether it’s the top or bottom of the inning. Therefore, the arrow pointing up and the “3” indicates that it’s the top of the third inning.
  • Now, let’s look at the “3-2” with the two gray circles underneath. The 3-2 refers to the batter’s count. For those of you who are baseball-challenged, a “count” represents the number of balls and strikes on a hitter. A batter who gets four balls is allowed to go to first base (called a “base on balls” or a “walk”). A batter who gets three strikes is out. So the “count” represents the batter’s status, and is always represented as numbers denoting balls-strikes (2-1, 1-2, 3-2, etc.). Therefore, 3-2 indicates that the batter has three balls and two strikes on him.
  • Finally, the two circles under the count represents the number of outs. Each blue circle represents an out (there are three outs in an inning). That these circles are gray indicates that there are no outs in the inning. (And no outs, with a 3-2 count, and two baserunners are a pretty good indication that the pitcher — Wojciechowski — is in trouble.)

The point is that within a relatively small space, a great deal of information can be gleaned. This concept carries over into many concepts of design, including data visualization and interface design. A person who understands how to read that information can obtain a large amount of information from a well-designed graphic.

Whomever it was that designed this score display definitely knew what (s)he was doing. Kudos to the person who designed it. I think this is a great example of how good design can effectively convey information.

Archiving my talks, part 1: #SQLSaturday schedule PDFs — #PASS

With the imminent demise of PASS, I figured I should take Steve Jones‘ advice and archive my presentation links.

For this round, I went through all the SQL Saturday events where I spoke and downloaded the schedules. Each SQL Saturday schedule has a link to save it to PDF (there is an “Export to PDF” link at the bottom of each schedule).

I saved the PDFs to my ‘blog media and created links to them. You can download these schedules by going to my presentation schedule and clicking any link labeled “schedule PDF.”

For now, I’m only concerned with links hosted on PASS websites, such as SQL Saturday and PASS Summit (which I’ll do for the next round). I’m not as concerned (yet) with Meetup, YouTube, or podcasts I’ve done that are not hosted on PASS websites. I’ll update these links as I go along.

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.

“Your opinion matters…” Helping people by sharing your experiences

My wife and I have an anniversary coming up, so I started planning a getaway trip to celebrate. (Because of the pandemic, we decided to keep the trip short — only one night, and we’re not venturing very far — only about an hour’s drive from our home.) While I was making my travel plans, I started poking around my own TripAdvisor profile. I had posted a few reviews, and I thought I’d post a few more. I figured my experiences and opinions could help other people looking for travel information, and it’s entirely possible that, by the time you’re finished reading this article, I’ll have written a few more reviews.

One of the biggest reasons why I started my ‘blog was so that I could write about my own experiences for the purpose of helping people. Helping other people is one of my great passions, and while I can’t always help physically or financially, I can help by providing information. It’s what I do professionally, and it’s what drives me as a professional technical communicator.

However, you don’t have to be a professional technical communicator to help provide information. There are countless forums out there, covering nearly an endless number of topics, in which you are able to provide your feedback. You’re probably tired of hearing automated support lines that say “your feedback is important to us.” But feedback is important. Feedback is data. Whatever feedback you provide helps to make products and services better.

How often had you looked something up (e.g. an answer to a technical problem, a hotel review, suggested driving directions, etc.) and became frustrated because you weren’t able to find any information? If you’re an application (or any type of IT) developer, have you ever been frustrated because you asked for feedback about your product, and no one would give it to you? That feedback would’ve been valuable in debugging and improving your product. This is why QA testing is a big deal, and is usually a critical step in development life cycles.

This isn’t limited to just IT professionals. It applies to just about anything in which information is involved. If, for example, you were making travel plans and wanted information about a destination, have you ever been interested in, say, a bed and breakfast, but you couldn’t find much information about it, and no one had written any reviews about it? Those reviews would have gone a long way in providing information about that place.

A lot of us brush off the messages that say “your opinion matters.” The thing is, it really does. Don’t be afraid to express your opinion or to provide feedback. What you say can help someone make a better decision, help improve a product, or possibly change the course of someone’s business for the better.

Now, if you’ll excuse me, I’m going to go and write a few more TripAdvisor reviews…

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.