User testing is important — for documentation

Any application developer will (and should) tell you how important end user testing is for their product development. It’s an important part of the development lifecycle. Developers need to know if their applications actually work, if they work the way they’re intended, and if their interfaces can actually be used. Without user testing, developers put blind faith in what they produce, and they have to assume that their applications are perfect every time, all the time — which, as we all know, always happens. User testing is critical in ensuring that you create a quality product.

So how often does your documentation go through user testing?

I’ve said many times that document development needs to go through the same steps as application development, and this is one of those steps. It is (sadly) common for documentation to be released without being checked for accuracy or usability. This is another way in which document development gets absolutely no respect, whatsoever.

If you’ve written, say, a set of instructions, one of the best things you can do is to give it to someone to make sure (s)he can follow it. How (s)he follows it readily tells you how well it was (or wasn’t) written, what does and doesn’t work, what adjustments need to be made, and so on.

It may not even entirely be the wording that needs adjustment. How easily did the person find information within the document? Was it there but not easily found? Was it overlooked? User testing not only can determine content accuracy, it can also serve the same purpose as UX/UI in that it can determine how effective object placement and document layout is.

And like application development, user testing your documentation determines what adjustments need to be made before it’s released. Additionally, user testing isn’t just critical for development; it’s important for document maintenance as well. Documentation that hasn’t been adjusted for changed environments makes for inaccurate information. Much of that can be caught through user testing.

I’ve said time and again that document development needs to be treated the same way as application development. User testing is an important step in that life cycle. It determines that your document quality is improved when it is released. Without it, you run the risk of releasing bad, poor quality, or inaccurate documentation.

Keeping documentation simple

In my presentations, I preach that keeping it simple is key to effective technical communication. It takes effort to read (you can write this on my gravestone: reading is work!), and the less you make someone work, the more effective the document will be.

However, keeping things simple is easier said than done. Taking a complex concept and explaining it in simple terms is a skill (and it keeps me employed as a technical writer). So what can you do to simplify concepts?

Well, here’s a few tips that might help you out!

Keep it high level

This particular tip comes with a caveat: “it depends.” (If you’re a DBA, you’ll recognize this as being “the standard DBA answer.”) Among other things, it depends on your target audience, and it depends on the type of document you’re writing.

Consider the audience. If you’re writing for peers, chances are that you’d be okay with including technical jargon or abbreviations that your colleagues will understand. But if you’re writing for managers, other departments, external customers, or anyone who doesn’t understand the technology that you see regularly, chances are that you will need to keep it high level.

Most of these people don’t want to see, and often aren’t interested in, detail. I once had a manager who was fond of saying “don’t tell me how to build the clock; just tell me what time it is!” In other words, just get to the point. Don’t get bogged down in the details. Unfortunately, this is a habit that I see all too often with technologists who feel that they need to include every single little detail. Chances are, it isn’t going to be read. Don’t do it!

It also depends on what kind of document you’re writing. If you’re writing, say, a glossary of terms, a systems administration manual, or a data governance document, then yes, things will need to be spelled out and defined clearly. But if you’re writing a step-by-step guide, a checklist, or a quick-reference manual, things need to be interpreted in a few minutes, possibly even seconds. For example, if I’m writing a step-by-step guide, my rule of thumb is, if an instruction cannot be followed in a few seconds, the instruction has failed, and it must be rewritten.

Good writing matters

I said in my previous article that you don’t necessarily have to have command of a language to be a technical communicator. At the same time, the better command you have of a language, the better your writing will be.

In my documentation presentation, I cite an example of why good grammar matters. Take these two sentences which basically say the same thing, but one is written in active voice, while the other is written in passive voice.

  • The boy mowed the lawn. (Active)
  • The lawn was mowed by the boy. (Passive)

Question: which sentence is easier to read? I’d say the active voice (and I’m sure many English teachers would agree).

There are many more examples, I’m sure, where good grammar makes a difference, makes things clearer, and contributes toward more efficient writing. Bottom line: if you write well, your documentation is better.

Stop saying “PLEASE!!!” (Avoid filler words)

One of my biggest technical writing pet peeves is using “please” in technical documentation. I’ve written about this before. You are NOT asking people for a favor, you are TELLING them to do something! “Please” is a filler word that not only takes up space unnecessarily, it is downright annoying to read.

“Please,” however is not the only filler word to avoid. I don’t have a comprehensive list of words to avoid, but off the top of my head, words such as “like,” “professional,” “extremely,” and so on should be avoided. The more words that are added, the more difficult it becomes to read.

Some other statements may not necessarily be fillers, but they might not add anything, either. My advice: if you’re trying to tighten up a sentence, eliminate unnecessary words. If the sentence reads well without them, leave them out.

Use illustrations and examples

The adage that “a picture is worth a thousand words” is true! An illustration often describes a concept much better than just words can.

Which of these instructions would you rather follow? Would you rather follow this…

(Source: https://www.realsimple.com/beauty-fashion/shoes-accessories/tie-necktie)

…or this?

(Source: https://steemit.com/fashion/@ighoboss/style-made-easy-tie-knotting)

Even if I’m looking up an instruction, if it includes an example, I will often refer to the example first, and not even bother with what’s written, unless I have to glean some information from the text.

Use headings

Let me ask a question. If I wrote this ‘blog article without any headings, would you want to read it? You’d likely see lots of black text paragraphs without any idea as to what each one is about. Headings provide an overview of each section and topic. They provide a reference that’s easy for the reader to find what they want. They can even determine how a document is structured. Long story short: headings make a document easier to reference.

Let someone else do it

No, I’m not saying this as a cop-out! We all have our strengths and weaknesses, and for many people, writing and communication might not be a strength. So why not let someone else do the documentation heavy lifting for you?

Even if you’re not the one doing the actual writing, you’re still an important part of the writing process. It’s called being an SME (Subject Matter Expert). You have valuable information that you want to pass along. The writer is your interpreter. The writer will refer to you for information. (S)he will likely be asking you a lot of questions, which very much makes you part of the documentation process. Even a conductor is playing an instrument; (s)he is playing the ensemble that (s)he is directing. Being an SME is the same principle; you’re directing someone to do the actual writing.

Summary

These are only a few suggestions toward making your documentation better. There are many more ideas that I didn’t even touch, and they would likely make this article much longer than it already is.

Good documentation is essential for any business, and can often prevent issues before they arise. Keeping it simple goes a long way in making your documentation efficient and easy to follow.

When information is overlooked

I went grocery shopping the other day. I picked up what I thought were two identical bottles of salad dressing (in the photo above). I remember thinking how strange it was that they put the same bottles of salad dressing in two different spots on the shelf. Nevertheless, I took one from each side and tossed them in my cart. It wasn’t until much later, after I was home, when I looked in the pantry, saw the two bottles sitting together on the shelf, and realized that one was organic, while the other was not.

To be honest, I really couldn’t care less as to whether a food product is organic or not. I usually buy the regular product because it tends to cost less and usually has a longer shelf life. (Personally, I believe the purported health benefits of organic products are minimal and overhyped, but I digress; that’s not what this is about.) But what I am wondering is how I was blind to the fact that one said “organic” while the other didn’t.

I’m sure there are cognitive and behavioral studies as to why people are blind to certain pieces of information, but that’s a topic that goes beyond my level of knowledge or expertise. (Before anyone says anything about information bias, I will mention that while I do tend to buy non-organic products, I really don’t have a strong bias one way or the other.) Rather, what I’m writing about is the fact that information can and does get overlooked. So what do technical communicators and UX/UI designers do to combat this?

For starters, I’ll say that the fact that information is missed is a matter of when, not if. Using myself as an example, I’m the first to admit that I often have the attention span of a flea, and as such, I’ll often skim, as opposed to deeply read, documentation that isn’t my own. As such, I’ll often overlook information. Granted, many people are more thorough than I am, I’m sure, but I guarantee that everyone will miss at least one thing. We are humans, not computers, and we are not capable of scanning, parsing, and processing every little bit of information that comes our way, so it’s unlikely that we’ll absorb or retain everything that’s thrown at us.

This brings me to another of my mantras: reading is work. (You can put this on my gravestone.) Reading requires effort. The more effort that is required, the more something is likely to be missed. One of my biggest documentation pet peeves is anytime someone says “it’s right there in the documentation,” but when you look at the documentation, the information is buried like a Where’s Waldo puzzle. Nobody can be expected to find information like that, and people who insist that that is valid documentation are not, in my honest opinion, technical communicators. Bottom line: if you have an important piece of information, don’t expect it to be read if you bury it within bad design or a large black paragraph swath.

However, that wasn’t the case with the bottle of salad dressing. The bottle was clearly marked. Yet I didn’t notice it until I got home. So what can writers and designers do to mitigate missed information? I don’t know if I have the answers, but I do have some ideas.

For starters, placement matters (good designers understand this). I admit that I was confused that these bottles were on opposite sides of the same shelf. Maybe this wasn’t enough. Placing them on separate shelves likely would’ve helped. Or, maybe separating them a little from the other group of bottles (the documentation equivalent would be utilizing whitespace). Maybe even placing the bottles in a separate section dedicated to organic products might’ve made a difference as well.

Another idea would be to use different appearances, such as varying fonts, graphics, or colors. As you can see in the above photo, both bottles use white labels and feature a picture of a peach. That design led me to believe the products were identical, but yet, I completely ignored the fact that one said “organic” while the other didn’t. We often comprehend visual cues before text, so changing the picture or the label color likely would’ve been enough for me to differentiate them at a glance.

I’m sure there are other ideas as well, but the bottom line is that information can and will be overlooked. By considering better information design, the chances of information being overlooked can be minimized.

Tools are not documentation

I’ve been running into an issue that I’m not sure how to get around — mostly because it’s somewhat political, and I don’t like to play the political game — and it’s frustrating. Because the issue is work-related, I am intentionally skimping on the details, but I’ll give you the gist of what I’m dealing with.

I’m trying to document a procedure for engineers to obtain temporary administrative access. In order to do so, the engineer needs to fill out a form to request the access. I’m trying to write about how to find and complete the form.

I spoke to the form’s owner (this is where the political part comes in). I explained what I was doing. However, he keeps insisting: “it doesn’t have to be documented, because the form is the documentation.”

He showed me a screen shot of text on the form that explains how the particular request works. The text made a lot of sense, and it would have been ideal to fulfill at least part (if not most) of my needs. I decided that I would create a reference to it. So I looked around the form for it… and could not find it anywhere.

He finally told me that “you had to click a specific button on the form to view the text.”

How was I (or anyone) supposed to know that? (Answer: you couldn’t.) Just by that alone, he contradicted his statement that the form is documentation. (It isn’t.) I wrote about this earlier; he is under the (potentially) dangerous assumption that everything on it is obvious. (Disclosure: the form in question is exactly the same one that I wrote about in the previous article.) He keeps insisting that the form is the documentation. But in spite of that, he gets frustrated that his department continually fields questions about how to do things that could be handled by the form — if it was properly documented. if the form actually was the documentation, it violates a major principle of technical writing: documentation is like a joke. If you have to explain it, it doesn’t work.

Now, I will mention that I like the guy. He’s personable and pleasant, and I do enjoy talking to him. But he is stubbornly clinging to his belief that his tool is the documentation. I try to explain to him that it isn’t, but he won’t have it. And I have to admit that I’m not sure how to handle it.

I pinged the project manager to get her thoughts on how to handle this (I’m still waiting to hear back from her as I write this). She has a better rapport with this person than I do, so she might have some insight as to how to handle this. Nevertheless, I think this is another case where you need to keep an open mind to improve a product, and realize that tools are not necessarily obvious in how to use them. Even a hammer can do more than just drive a nail.

When information is removed (or, Never Assume It’s Obvious, Part 2)

I have an app for my local convenience store that I use to purchase various items, including, among other things, gasoline. On my way home this afternoon, I decided I needed to put gas in my car and stopped at the store to do so.

To use my app to buy gas, I need to input the store number (usually not a big deal — it automatically detects my store location, and does a good job of it) and the pump number. I opened the app to input the pump number, then looked at the pump for the number… and looked, and looked.

Hey, what happened to the pump number?

I looked at the pump. The number was nowhere to be found. Upon closer inspection, I saw a clean square area on the pump — where the sticker identifying the pump number was once located.

I looked at the other pumps. Same thing. No identifying numbers on the pump. At this point, I had spent several minutes trying to figure this out, and I was starting to get irritated.

I finally noticed it. The only place where you could find the pump number was on the sign above the pump (similar to the picture above).

Let’s be honest, people. How many of you would’ve thought to look UP to find the number, and not on the pump itself?

The app has a feature that allows me to send feedback. I finished filling my tank, got in my car, and used the app to send a very irate message. I’m not going to lie. I was (and still am, as I write this) very irritated. There is absolutely no way that it should’ve taken me several minutes to figure out the pump number.

Additionally, the stickers didn’t just have the pump numbers; they also had the store number. I mentioned that the app does a good job of identifying what store I’m shopping, but what if it isn’t working for whatever reason? (Note: I’ve had that happen before.) Also, it serves the purpose of confirming that the store number that appears on the app is correct.

I’m hoping that the store was looking to upgrade the stickers on the pump, but of course, I didn’t (and still don’t) know if this was the case. In the meantime, the fact that they removed information from the pump made it more difficult for me to do what I needed. What I feel, however, is that whomever made the decision to remove the numbers — a horrible decision, in my honest opinion — decided that the numbers on the signs above the pumps were enough, so the numbers on the pumps themselves were no longer necessary.

I wrote earlier to never assume that anything is obvious. This doesn’t just apply to documentation; it applies to everyday objects as well. Not including this critical information someplace where it can easily be seen (numbers on the sign above the pump does NOT count as “easily seen”) is a blatant example of information ignorance and horrible design.

Never assume it’s obvious

When I was in college, I remember a professor who seemed fond of saying “it’s intuitively obvious.” I don’t remember a lot from that professor (other than that he was a good professor and a good man), but I vaguely remember my classmates making fun of that line, partially because he used it often, and partially because it often was not “intuitively obvious.”

How many of you remember way back when the “this beverage is hot” warning labels started appearing on coffee cups? Many of us (myself included) ridiculed it, responding with, “duh!” But of course, there is usually a good reason behind the story. Now the hot beverage warning label is ubiquitous on nearly all hot beverage cups, and most of us don’t give it a second thought.

I was reminded of this yesterday as I worked on a project. I won’t go into the details (I don’t like to share details of an in-house work project), so I’ll give you the high-altitude view of it. I’ve been trying to solve a problem where multiple people are asking IT Support for assistance, and IT Support is overwhelmed by requests. IT Support does have a website where many of these questions can be answered, but it seems that people either don’t know it exists or don’t know enough to look for the answers there.

I went poking through the website. It did seem to have the tools necessary to answer many questions, as well as resolve a few issues I’m working on. It then occurred to me — the very fact that I was poking around the site to figure out how it worked. In other words, it wasn’t entirely obvious as to how to get the answers from the site. It occurred to me that what was missing was a user guide for the site. I’ve been pitching it to several people, as I believe it’s a good idea, and I think it will resolve a number of problems. Nevertheless, I’ve gotten a little bit of pushback, along the lines of, “of course it’s obvious how to use it,” and “we have links everywhere that explains how it works.” (Also, IT Support, as just about any department, tends to get somewhat protective — understandably so — of its assets and material.)

So if it’s so obvious, then why are you getting overwhelmed with questions?

As a technical writer, “never assume it’s obvious” is one of my biggest mantras, and I think it should be for anyone involved with technical communication, UX/UI design, teaching, or documentation. Simple instructions can often be overlooked (how many times do I have to say that reading is work?!?), and people from other cultures may not always understand the language or context that you’re writing, so that’s something else to consider.

Never, ever, assume anything is obvious — because more often than not, it isn’t.

Rocket Companies TechCon ’21 — I’m speaking!

The speaking gig train keeps rolling!

I received an email this evening saying that I have been selected to speak at Rocket Companies (formerly Quicken Loans) Tech Con ’21! This is a virtual conference scheduled for Wednesday and Thursday, October 20 and 21!

I will be doing my “original” (as in the one that started it all for my speaking career) presentation about how to speak the language of technology to those who don’t understand it!

This event is actually a bit of a milestone for me; this is my first event that is not a PASS-related (or former-PASS) sponsored event (such as a SQL user group meeting, SQL Saturday, Data Saturday, or PASS Summit)!

As of right now, I don’t know what day or time I’m speaking; all I know is that it will be one of those days in the afternoon (Eastern time). As soon as I’m scheduled, I’ll post the date and time!

It’s not them, it’s you #Documentation #ClearCommunication

A friend of mine (you know who you are) posted this to his Facebook this morning. Ostensibly, it’s in response to the growing controversy about the New York State governor (I won’t go there; that’s not what this is about, and I still despise politics), but my friend’s post was so compelling that I thought it was worth sharing.

As a professional communicator, I can’t tell you how many times someone either delivered a talk or a document and became frustrated when (s)he didn’t understand why his or her message did not get conveyed. Granted, in some cases, it might be that the sender is not a native speaker of the language and doesn’t know it well enough to convey his or her message. For those people, I’ll cut them some slack.

However, I am continually frustrated by people who insist that (s)he wrote a great document, only to find that what (s)he wrote was so obfuscated by detail, technical jargon, lack of organization, an avalanche of information, poor command of language, lack of understanding about design, or other reasons. This is the kind of thing that keeps me employed as a technical writer.

I’ve written many times before that it’s often the sender’s responsibility to ensure the message is clear. For example, I’ve come across too many instances (and I still continue to) in which a technician, writing a document, keeps insisting on including every little piece of detail in his or her document. And I continue to pound into people’s heads that reading is work!!!

So to my friend who posted this this morning, all I’ll say is, thank you for supporting my passion and my mission. This is exactly what drives me to do SQL Saturday and Data Saturday talks. And I’ll continue doing so until people get the message.

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.

Our user group logo gets a makeover @CASSUG_Albany #Logos #Branding

As some of you might be aware, I’m the person who handles communications and branding for the Albany local SQL user group. As such, I’m responsible for sending out group announcements, updating the calendar of events, and maintaining whatever social media resources we might have.

Our old user group “logo”

Last week, I was preparing the announcements material for our April meeting, and in doing so, I took a long look at our “logo” (seen here on the right). There were many things that I found amiss. First, the logo, which we had had for several years — I’ve lost track of how long — was unwieldy and no longer representative of our group. Second, it used the PASS branding (and the REALLY OLD branding at that), which needed to be removed since PASS ceased operations in January. Finally, it was not dynamic — we were using it universally as a logo and an icon, and it really did not function well as such. I spoke to Greg and Ed, our user group’s co-admins, and got their blessing to come up with a new logo for our group. (Besides, I needed the design practice!)

One idea that I tried…
…and another

I sat down and tinkered with some ideas. I tried out some fonts and visual schemes. Ideally, I wanted to incorporate some specific design elements: New York State, something representative of the Albany Capital Region where we’re located, a technical-looking font, and the universally-recognized (at least to data professionals) database icon. I wasn’t sure what kind of color scheme I wanted to use, but as it turned out, I started out using blue and gold for the fonts (which, unofficially, are considered to be New York State’s colors), decided that I liked them, and stuck with them.

My initial idea was to superimpose the user group acronym (CASSUG) over the outline of New York State; those are the designs you see here to the right. I tried a couple of different fonts, including one (which you see in the second image) that included NASA in the font name. (I decided that I liked the other font better.) I positioned the database icon over where Albany is located, which would satisfy my requirement of representing the Capital Region.

While I was generally happy with the results, I also wanted to take another approach. I downloaded a line drawing image of the Albany skyline and placed the CASSUG text logo underneath it. I liked the idea and decided to run with it; however, I needed to find another image, as the skyline image I used could potentially have violated copyright restrictions (I did not post it here for exactly that reason). I had to find another image, but I was unable to find one that I liked. I decided that the only way I could come up with a suitable skyline outline image was for me to create my own.

I opened MS Paint and hand-drew a simple representation of the skyline. I decided to represent four local landmark structures in the drawing (and anyone local to the Capital District knows that one of those structures had to be The Egg — it is the one landmark building that instantly identifies the Albany skyline, just as much as The Pyramid identifies Memphis, the Carrier Dome identifies Syracuse, or the Space Needle identifies Seattle).

I thought the outline came out fairly well, but I had to make sure that I did it justice, so I posted it to my Facebook and asked local friends if they could identify the buildings. (If you’re looking at the logo at the top of the page, the buildings represent, from left to right, the Corning Tower, the Egg, the State Capitol, and the Smith building.) The outline was not to scale and it wasn’t perfect, but it didn’t have to be; it just needed to be recognizable. Everyone correctly identified The Egg, and most people were able to correctly identify at least two of the four structures. That people recognized the skyline told me that I had done my job.

I placed the CASSUG acronym and accompanying text underneath the skyline outline. I wanted to make sure the acronym was spelled out for the benefit of those who wanted to know the acronym’s meaning. As a final design idea, I took the New York State outline, placed it to the right of the acronym, and superimposed the database icon on top of it.

The end result is the image that you see at the very top of this article.

I ran my ideas past the user group members, and people overwhelmingly said they liked the Albany skyline image.

I like how the image came out. I intentionally created a relatively large image (2830 x 1250px); you can create smaller images from a big one, but you can’t create big images from a small one. The image is versatile; for example, if we need a banner, we can use the acronym and text without the skyline; if we need a thumbnail, we can use the icon over NYS, and so on. I started updating our Meetup page with the new design, and I’ll incorporate it into other materials as well.

What do you think about my rebranding effort? Like it? Hate it? Let me know in the comments below.