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.
My first instinct would be to shut down this monstrosity of a system. However, it likely wouldn’t be a good idea to shut down what might be the only means for an applicant to contact the human resources department. That said, this system is so badly designed that it’s likely to deter anyone trying to apply for positions, anyway. That gives me two options: either leave it as is, or implement a simple temporary replacement. Personally, I wouldn’t want anyone else to experience the horror show that I experienced, so I would opt for a simple replacement. The simplest option would be “send your resume, cover letter, and the position to which you want to apply to <such and such email address>.” Or, if I wanted to kick it up slightly, I’d make it a simple form: name, email, and a place to upload your resume.
If I opted for the form option, that would preclude some back-end mechanism to handle it. The simplest option would be to take that form data and put it together into an email that would format it, attach the resume, and send it to an email address. Of course, this opens another can of worms. First, there’s the matter of security. Who knows what viruses or Trojan horses are lurking in an attachment? Most forms like these ask for specific file types — usually a Word doc or a PDF — so I’d only allow those formats. I would also make sure that all security and antivirus functions are up-to-date; if a message does include a virus, at least it can be caught at the email application level, and it would be a matter of the cybersecurity team to investigate it further.
Once the temporary option is in place, and the horrendous system is shut down, I’d look into whether it’d be better to implement a new system out of the box, or roll my own.
Let’s start with rolling my own. I’d likely look into something using a SQL Server or Azure back-end (probably the latter, since everyone seems to be moving to the cloud, although that would require some brushing up on my part, since I don’t have a lot of cloud development experience). I’d probably put together a .NET front-end. Security, of course, would be a major issue to address, since we’d be dealing with applicant data. I would make sure that applicant data can be saved and pulled whenever an applicant applies for positions, eliminating the need for the applicant to continually re-entering his or her information, other than his or her login information. Again, the point is to make it easier, not harder, to apply for positions.
That said, there are a number of turnkey options that might be able to do the job better than I can. ICIMS is a popular SaaS product used by a number of employers. I would also look into other CMS systems that might exist. Other than ICIMS, I’m not sure of other applicant systems that can do what is required, but I don’t doubt that other systems exist that can maintain applicant data quite well. In this case, I’d switch my role from that of a developer to one of an analyst or consultant; what steps would I take to implement such a system? It would depend on the system and the environment.
Regardless of what system is used and how it’s implemented, any of these solutions would be better than the disaster of an application that I experienced.
In my job hunt experience, I might have come across what may be the worst online job application I’ve ever experienced — so bad that I felt a need to write about it. I will not identify the institution, other than it is a well-known institution in the Albany Capital District. Maybe if a representative from this institution is reading this article and recognizes that it is theirs, they’ll realize what a horrible experience this is, and takes steps to fix this problem — and yes, it is a BIG problem. I consider this a case study in how NOT to set up an online job application.
In my job search, I started looking into specific companies to which I could apply, so I went to this institution’s web site. I went to their careers section, found a few positions that I thought were interesting, and started applying for them. This is where the horror show begins.
Most online applications that I’ve experienced generally have an option for you to create a profile that includes your identifying information, resume, background, and so on. Indeed, I had applied to this particular employer years ago, and they had such a system in place back then. I poked around to see if I could find my previous profile, but I couldn’t find any such link. I figured, no matter; they probably had my old email address back then, so I’d probably have to create a new one.
As it turned out, this was a red flag.
Throughout my past several months of filling job applications, I’ve gotten used to ATS systems that read your resume or LinkedIn profile and autofilled job applications based on your resume and profile. I’ve had mixed success with these systems with varying levels of frustration, but for the most part, they’ve saved me a great deal of time and effort with applying for positions.
Unfortunately, for this employer, there was no such system. I clicked the button marked “Click Here To Apply.” It took me to a page that had this interface.
(At this point, I want to point out the part that says “You may add additional positions to this application.” I’ll come back to this later, but let me say that  during this first run-through, I wasn’t thinking about other positions yet, although there were others that interested me, and  I did not see this on the first go-round. Those of you who follow my post regularly know how much I emphasize that “reading is work!!!” Again, hold this thought; I’ll come back to this.)
Okay. I clicked Continue. The next screen was the standard HR-ese about EEO and code of conduct. I clicked the requisite box and clicked Continue again.
The next screen asked me to fill out my name, address, email, and various other boxes (“have you ever worked for [name of employer] before,” etc.).
Wait a minute. It’s asking for my name. Shouldn’t it ask to upload my resume or connect to my LinkedIn account? I looked around, and there was no such button or link. Okay. I filled the requisite fields and clicked Save & Continue.
The next screen asked questions such as date available to work, salary requirements, relatives that work for (name of employer), and so on. Again, I answered what they asked, and once again, clicked Save & Continue.
The next screen displayed the following.
I took issue with this question, particularly with the “highest graduate education year completed.” I have a Masters degree, I went to school part-time, and it took me 4½ years to get it, taking a class per semester (and a summer session) as my schedule allowed. So does that mean I click 4 (as in it took me 4+ years), or do I click 1 or 2 (as it typically takes to get a Masters degree full-time)? It did not specify, and there were no instructions. I don’t remember what I answered (I think it was 2), so I went with my best guess as to what they wanted.
Directly under that question was this.
Wait a minute. You haven’t asked me to attach a resume. I suppose it’ll ask me later (I still don’t understand why it didn’t ask me to attach one at the very beginning). I clicked Save & Continue.
The next screen asked about job history.
I already have my employment history on my resume (which you still haven’t yet asked me to attach, upload, or link). You really want me to take the time to fill this in? This screen frustrated me; I’ve been working professionally for thirty years. You really want me to fill all of that in? And why aren’t you autofilling it from my resume (that you still haven’t asked for yet), like everyone else using ATS is doing? The application only asks for at least four years of employment history, but I’ve only worked for a few companies over four years, and it doesn’t tell the entire story of who I am or my professional history.
Nevertheless, the application system had me over a barrel, so I had no choice but to fill it all out. Let me emphasize that the form is not easy to fill out; all dates are drop-down selections (which, I should add, don’t work very well), they don’t auto-format fields such as phone numbers (e.g. they don’t limit area codes to three digits), and you have to fill out the fields for employer, title, job description, and so on.
I don’t know how long it took me to fill it all out. I’ll estimate that it took between fifteen and thirty minutes. It felt like several hours.
It next asked for personal references, if I had fewer than two employers. Since I definitely had more than two employers, and I didn’t feel like filling out more than I had to, I skipped this step. (And I should note: what if I worked ten years for only one employer? Yet another problem with how this application was put together. Whomever it was that put this together was obviously not thinking.) Again, I clicked Save & Continue.
At this point (step 8 of 12, according to the application), it asked to upload documents (resume, cover letter, etc.). It only allowed up to two documents (most other applications I’ve filed allowed for more than two). Okay. I added my resume and cover letter, and clicked Save & Continue.
Finally, it got to the point to review everything I’d filled out (very painfully, I should add). I clicked Save & Continue. Subsequent screens displayed the requisite EEO questions — race, veteran status, and so on. I clicked through the screens. My application was submitted.
At this point, I went back to apply for other positions that interested me. It was here where the employer’s application went from being frustrating to downright infuriating.
Almost all automated job applications send an email acknowledgement, so I looked for one after I finished the arduous procedure. I didn’t see one. After waiting for several minutes and poking around my email, I finally found this sitting in my spam folder.
It sent it as an attachment? No wonder why it was flagged by my spam filter. Since I trusted the sender (or, more accurately, I knew from where it had been sent), I went in and followed the instructions. Okay, fine. I downloaded it and followed the sign-in instructions. It had me sign into their system, where I found this message.
Granted, there was no identifying information (other than my email and the employer, which I blacked out in this screen capture). Now, I am all for data security and ensuring data is protected, but did this message warrant sending a secure attachment and requiring a login? I don’t think it was. I’ve gotten other emails from job applications that included more information that was sent less securely. One other thing I found infuriating was that there was absolutely no reference to the position that I had applied. I’ve been using my email to keep track of applications. How am I supposed to know to what position this refers? In my opinion, this message was not worth sending in a super-secure email. I felt that the mechanism they used to send this message was overkill.
I had seen other positions on the list that interested me, so I went back to apply for them. I figured that the system would take my information from the previous application and use it for the new application.
I figured wrong.
There was absolutely NO mechanism to refill all the information from the previous application. There was no applicant account function, no resume or LinkedIn ATS autofill function, nothing. If I wanted to apply for another position, I had to refill the ENTIRE application manually. Did I mention how painful and tedious it was to fill the application? It might as well have taken several hours to do so.
Now, remember earlier how I mentioned that there was a link to “add other positions to your application”? I did not see that the first time around. The next time, I tried it. The link brought me back to the ORIGINAL job search page. There was NO function to add any other jobs to an existing application. Nothing like that was anywhere to be seen. And if it did exist (and I’m not sure that it does), it is not obvious.
This application system design is so horrendous that it’s saying “f**k you” to applicants. It is doing more to drive applicants away than it is to make them want to apply for positions.
This is not the first time I’ve written about bad form design. However, this problem isn’t just about the form; it’s also about the entire application process. The design planning was poorly thought out, if it was done at all. There is no mechanism for autofilling fields. There is nothing to save applicant data. The forms are not intuitive. And I’m willing to bet large sums of money that either there was no end user or QA testing done, it was done shoddily, or test criteria were poorly defined.
I could keep going, but to make a long denunciation short: whomever it was that put this together has absolutely no business working on UX/UI projects.
The object of well-designed UX/UI and online forms is to make it easier, not harder, for end users. As an applicant, I found this process to be infuriating, not just frustrating. A process this bad will likely deter qualified applicants from applying to jobs. And if this system is that badly designed, these applicants are likely to question whether they want to work for this employer in the first place.
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 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.
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.
After I logged into my computer, a pop-up window appeared. It was my Docker application, telling me that an update was available and ready to install. Okay, I said to myself, and clicked the button to proceed.
Except… nothing happened.
I clicked it again. And again. And again. I mashed the mouse button. Nothing. I decided there was a problem with the interface, went on with my work, and forgot all about it. At one point, I saw a Docker window appear, saying updates were being applied. Okay. Again, I went back to what I was doing.
I didn’t think anything of it — until I looked at my taskbar several minutes later. All along the taskbar were several new — and identical — icons that I hadn’t seen before, roughly one for each time that I had hit the mouse button. When I clicked each icon, I was greeted with a window that said “installation failed.” Well, almost all. The second-to-last one I clicked said, “installation succeeded.”
Yet another example of horrible design rears its ugly head.
As an application end user, if I click something where it says “click here,” I expect — and demand — that it does something. It doesn’t matter what it is. Granted, I would prefer that it performs the action that I expect when I click it, but even if all it does is change the mouse pointer, display an “in progress” icon, or display an error message, I expect some kind of response that indicates that my action did something.
An action that results in nothing is a huge pet peeve of mine, and, in my opinion, is extremely horrible design. A click that does nothing tells me that the application is doing exactly that: nothing. Having an action with no response is not only annoying, it can be potentially dangerous. What if — hypothetically — clicking a button resulted in lost data, but there was no indication as such?
A reaction is a form of feedback. If I click a button, a reaction — even if all it is is an in-progress icon — tells me that the application is doing something. If I click a button, and it does nothing, then I expect the application is doing nothing. An action without any reaction results in frustration on the part of the end user, and potentially dangerous side effects if the application performs an action that the user doesn’t expect.
If this is how you design your UX, then you need to rethink your design. When it comes to interfaces, every action must have a reaction.
Within the past week, I came across a couple of examples where designers, in an attempt to make something “aesthetically pleasing” ended up creating a bad design.
The first example, strangely enough, came from a public toilet (don’t worry, I won’t go TMI on you). The flush mechanism was similar to what you see here. It was dark in the toilet stall, so I couldn’t see the little graphic of the finger pressing the button (that you can see clearly in this picture). It looked like one of those auto-flush mechanisms, so I expected it to flush when I stood up. It didn’t. I tried pressing the top of the mechanism and waving my hand in front of it. No dice. It wasn’t until I found the little button along the front edge that I finally got the thing to work. I don’t know how long it took me to figure that out, but I’ll estimate that it took me somewhere between fifteen and thirty seconds — far longer than it should’ve taken me to figure out how to flush a toilet.
The second example happened recently at a friend’s house. The photo you see here is the ice and water dispenser on his refrigerator. I put my water bottle underneath, and naturally, ice came out of it. I then tried to get water. How do I do that? I looked for a button to toggle between ice and water, but couldn’t find one. My friend told me to press the button above the ice dispenser. I pressed the top panel with my finger, expecting my bottle to fill with water. Much to my surprise (and my chagrin), water came out not from under the button and into my bottle, but rather above the panel I was pressing, splashing water onto my hand. Apparently, what I was supposed to do was press the upper panel with my water bottle so that it would dispense into my bottle.
To the people who designed these things: how was I supposed to know that?!?
These are more examples of what I consider to be bad design. It seems like artisans are making more of an effort to make products visually appealing. But in their efforts to make things “pretty,” they’re ignoring making them functional.
Years ago, I remember seeing signs in a local park — “park here,” “keep off the grass,” etc. (I tried to find pictures of them, but have been unsuccessful.) Whomever made the signs went through great efforts to make them look pretty — the person used wood and tree-themed graphics to dress them up and make them look “rustic.” However, the person concentrated so much on making the signs “pretty” that (s)he completely ignored making them readable! The signs were impossible to read. You could not tell what they said. Thankfully, the signs have long since been replaced, and personally, I think the sign-maker should have been fired.
People might argue that, “well, of course they’re functional! You just have to know how they work!” Therein lies the rub: you have to know how they work. Making something functional isn’t just a matter of making something that works; it needs to be obvious as to how it works! This is one of my major pet peeves when it comes to design. As someone once said, good design is like a joke. If you have to explain it, it isn’t any good.
While working on a user guide, I realized that I had administrative rights to the application I was trying to document. That was all well and good, except that I was trying to write a non-admin user guide, and I needed to know how someone who didn’t have admin rights saw the application. Fortunately, one of my co-workers sent me an application URL and a testing user login I could use that simulated exactly what I needed.
That brings me to today’s article. Many application development environments make use of a sandbox, or some other development, environment where a developer can play to their heart’s content — that is, some place where someone trying to test or develop applications can play with the app without having to worry about breaking anything important. That same testing environment is just as important for a technical writer.
Much of my work as a technical writer involves putting myself in an end user’s shoes. I’ll often go through an interface and document the steps a user might use, what a user might see on the screen, and the effects of certain buttons and links. One of my most frequent questions when I work on documenting an application is, “what happens when I click this?” After I do so, hopefully my next response isn’t “oh crap!”
This is why a tech writer needs access to a testing environment. Like application developers who need to test within a safe environment, a person documenting the system needs to be able to document the system and be able to do so knowing that (s)he won’t adversely affect the application by playing with the system.
I wrote previously that a tech writer can help an application developer, and vice versa. Indeed, the tech writer can function as an in-house QA analyst. In order to write good documentation, the writer needs a realistic environment in which (s)he experiences what an end user might see. Having a sandbox environment in which a writer can “play” provides exactly that type of environment. As an added bonus, not only does this allow the tech writer to produce better documentation, it allows that person to provide feedback regarding the application, which ultimately results in a better application.
This morning, I had an issue with my LinkedIn account. I was trying to reply to a message, and I kept getting “Send failed.” That was all I got — there were no error codes, additional information, or symptoms. I poked around LinkedIn’s Help section, and came across this page for dealing with messaging problems. I didn’t go as far as to clear my cache, but I did log out and back in, and I tried it in a different browser, all to no avail. In the middle of contacting LinkedIn’s support, the problem mysteriously “fixed itself.” If you work in tech, I don’t have to tell you how frustrating it is for an issue to mysteriously “fix itself.”
However, the issue I had, in and of itself, is not why I’m writing this article. When I heard back from LinkedIn, I got a message saying “go to this page” (the one I’d already found) and use that to troubleshoot. In response, it displayed the interface you see above. As you can see, they only gave me two options: “yes, I’m good,” and “no, I still need help.” The problem was, my response was, neither. No, I didn’t need help at that point, but I also wasn’t completely good, either. I wanted to inform them what had happened in case they wanted to investigate it further. But they did not give me that option. Between those two options, I clicked “yes, I’m good,” which immediately closed the case; I had absolutely no recourse to add more to it. I looked around for ways to send feedback, but I did not find any good way to do it. Replying to the email resulted in a response saying “you responded to an unmonitored mailbox.” The more I looked for a feedback mechanism, the more frustrated I got. The issue quickly went from “I’m reporting a technical issue” to “you guys need to fix your UI/UX.”
Let me start with the UX/UI design. I strongly felt that only those two options, especially if answering “yes” automatically closed the case, was a very poor design. As many people will tell you, the answer often isn’t simply “yes” or “no.” (One of the long-standing jokes among DBAs is that the standard DBA answer is, “it depends.”) And even after I clicked one of those buttons (in this case, I clicked “yes”), the interface was confusing. I was brought to a page that said “click to enter more information” (or something like that). The problem was, click where? None of the “links” allowed me to enter anything else, and there was no clearly logical eye path for me to follow. I had no idea what I was supposed to do once I got to that page. I kept clicking different links, trying to leave feedback. By the time I found a link, I wasn’t even sure that I was replying to my original query. I had no idea to what — or even where — I was responding.
I’ve said time and again that if you’re a technical writer — or a UX/UI developer — you don’t want to make your reader or end user work. Reading is work. Making your end user work is a sign of poor design.
Second, this experience made me question just how seriously LinkedIn takes feedback. True, nobody wants to hear bad feedback. I know I sure don’t. But if you want to improve, you need to know what it is you need to improve. How am I supposed to improve something when I don’t know what it is that I’m doing wrong? Not including a channel for feedback — or making it difficult to do so, as I allude to above — is doing a disservice to your organization and to your clients.
Good communication between you and your client is important. Not only does it help your client, it helps you improve your organization, and it builds trust between you and your customers. Making it difficult for your customers to communicate alienates them — and ends up hurting your business in the long run.
One of my current projects involves documenting processes for an application that are still under development. As such, much of what I write may change, depending on how processes are changed during the course of development.
At one point, I tested one of the processes so I could determine functionality and document it. In doing so, the process came back with an error message that I wasn’t expecting and didn’t have any user-friendly information, other than a cryptic error code. I contacted one of the developers working on the application and told him what I found. I gave him the error codes I experienced and steps I took to get them. He told me, “you’re coming across bugs that we didn’t even know we had.”
It occurred to me that I was doing more than just documenting the application. I was also acting as a beta tester.
One aspect about writing technical documentation is learning about what you’re writing. In order to write about a process, you need to understand how it works. If you’re documenting an application, the best thing you can do is run the application in a safe environment (such as development or a sandbox), learn how it works, and use it to document steps and capture screens. In doing so, you come across application bugs and even come up with ideas to make the application even better.
I’ve long argued as to the criticality of documentation. It records important information and serves as a reference. However, until this point, it didn’t occur to me that the document development process could have a symbiotic relationship with application development. To me, this adds further fuel to the argument that documentation is critical and required.