Writing UI text—less is more, taken to the extreme

Less is more is a mantra frequently heard in technical writing. When applied to editing, this works out to be something like, “After writing, keep taking the words out until it stops making sense, then put the last word back in.”

While this approach applies to technical writing in general, it comes into sharp focus in user interface (UI) text where both time and space are in very short supply. The reader/user is often in a hurry and there’s no space to put any extra text.

The key to success with such approaches to minimalism is to know your audience. I’d like to share a couple of examples of knowing your audience and how this resulted in two different outcomes.

The examples

The first example is an interface from the piClinic research project I conducted from 2016-2019. In that project, I was trying to learn if limited-resource clinics in Honduras that used a paper-based records with no automation could successfully adopt a small-scale computerized record keeping system. This project was low budget in every dimension, but I’d researched the requirements thoroughly and felt like I understood the user well enough to design a system that would work for them. The field tests in 2019 confirmed that hypothesis.

The second example is from a recent update to the Amazon Web Services (AWS) Console interface that I worked on. In this project, I collaborated with a talented team of UX designers, program managers, and developers to update the interface and improve its usability. My role was primarily the text on the interface; however, the text, design, and implementation are all intertwined.

Compared to the piClinic, the AWS project had much more talent and support behind it. In retrospect, the budget certainly influenced the design and the implementation of each project, but the approach to crafting the words used (or not used) in each of the interfaces had a lot in common.

The text in both interfaces was designed to meet the target users where they are.

Continue reading “Writing UI text—less is more, taken to the extreme”

If we could only test docs like we can test code

Postman logo
Postman logo

As I continue to catch up on delinquent and neglected tasks during the inter-semester break, I’ve started porting the software from last year’s piClinic Console to make it ready for prime time. I don’t want to have any prototype code in the software that I’ll be leaving in the clinics this coming summer!

So, module by module, I’m reviewing the code and tightening all the loose screws. To help me along the way, I’m developing automated tests, which is something I haven’t done for quite a while.

The good news about automated tests is they find bugs. The bad news is they find bugs (a lot of bugs, especially as I get things off the ground). The code, however, is noticeably more solid as a result of all this automated testing and I no longer have to wonder if the code can handle this case or that, because I’ll have a test for that!

With testing, I’m getting to know the joy that comes with making a change to the code and not breaking any of the previous tests and the excitement of having the new features work the first time!

 I’m also learning to live with the pain of troubleshooting a failed test. Anywhere during the test and development cycle a test could fail because:

  1.  The test is broken, which happens when I didn’t update a test to accommodate a change in the code.
  2. The code is broken, which happens (occasionally).
  3. The environment is broken. Some tests work only in a specific context like with a certain user account or after a previous test has passes.
  4. Cosmic rays. Sometimes they just fail.

The challenge in troubleshooting these test failures is picking the right option from the start to make sure you don’t break something that actually was working (but whatever was really broken is hiding that fact).

But, this is nothing new for developers (or testers). It is, however, completely foreign to a writer.

Here are some of the differences.

Continue reading “If we could only test docs like we can test code”

What were they thinking?!

Design reviews or critiques are a favorite pastime. While my righteous indignation of having to suffer a bad website can still evoke some pointed criticism, I’m trying to keep things in perspective.

I’ve talked about critiquing designs in the past, but here, I’m talking about those informal critiques of designs created or constructed by other people or organizations. You know, the ones that usually start with “WTF were they thinking!?!”

The objects of such informal critiques are legend. A search for design fails in Google returns 270,000,000 results to me (in 0.3 seconds, so it must be a popular search). I remember talking about some of these design fails in design classes, but I’ve been involved with designing, building, and shipping long enough to know these examples of design fails are team efforts.

Full disclosure, I still shout “WTF?!” from time to time in spite of the following introspection, but my hope is that reflecting on these points will help me view them with a little more perspective. I write this so that you might, as well.


Let’s start with that point when you’re using a website that is sporting the latest version of Gordian-knot navigation or TV remote control and you’re wondering aloud how anyone could design such a mess, let alone ship it for what seems like the sole purpose of causing you grief. Of course, YOU would NEVER commit such a crime against humanity!

Would you?

Have you? (Be honest.)

If you’ve shipped more than one or two documents, products, web-sites, or you name it, then in all likelihood you, too, have published or shipped something that someone, somewhere, at some time will say WTF?! when they use it. It’s almost impossible not to and here’s why.

Why do people ship bad designs?

Continue reading “What were they thinking?!”

What’s a piClinic Console?

Image of piClinic Console prototype which consists of a monitor, keyboard, and mouse
piClinic Console prototype

So, I’m taking a break from technical writing related thoughts and posts for a while. For the next two months, I’ll be focusing on the development of, I suppose you could call it, my side project for the past few years. While, I’ve been working on this for the past four years, or so, it’s starting to gain some momentum.

The piClinic Console.

The project’s website, http://piclinic.org, says,

“The piClinic is an open-source, patient-record automation solution designed for limited-resource healthcare clinics around the world. piClinic systems fill the gap between a paper-based patient-record system and a complete Electronic Health Record (EHR) system at a very low cost per system. The piClinic is built on the digital principles to provide an accessible, sustainable, and low-cost solution.”

No, seriously, what the heck is a piClinic Console?

Here’s the story.

Continue reading “What’s a piClinic Console?”

My GitHub is a mess and that’s a good thing

You’ll have to take my word for it (or find it on your own, I’m not trying to hide). I’ve seen where your GitHub account is treated as a developer’s code portfolio, and I think that’s a shame. I treat mine more like a code sandbox where I can go and play learn.

Having a portfolio is a good thing for those who want to show off such things; however, after having looked at a few open-source projects, I see more that are on the sandbox end of the spectrum than those on the portfolio end–by a 2:1 margin (I’d guess, I don’t count them).

One project that I’m in the middle of is definitely not anywhere near the portfolio end but it’s exactly where it should be. I’m using it to test out different ideas that, if all goes well, will inform the production version of the project, at which point, I’ll create a new repo that incorporates the best of the various experiments. Until then, it’s going to be where I do what I need to do to figure out what it is I want to do.

If you want to see how I’ve coded for money, you’ll have to look at examples in which I did exactly that. Unfortunately, I don’t have any copies of such work, except for maybe some old code examples I used in some documentation.

If you want to see what I’m tinkering with, feel free to check my GitHub Repo (after you find it).

Better to light a candle

My write up about the Hawaii False Alarm left me a little unsatisfied in that it really didn’t offer much in the way of actionable responses.  Fortunately, better minds than mine came to the rescue today.

What Healthcare.gov has to do with the Hawaii false alarm — and what to do about it showed up in my Twitter feed from Code for America and offered some more immediate actions for those who want to help. In that article, Erie Meyer suggests:

  1. Usability Test Your Most Important Services
  2. Adopt the Digital Services Playbook
  3. Get Help

Usability Test Your Most Important Services

While that might seems obvious to many, apparently enthusiastic government lawyers have been preventing usability testing in the past, according to an earlier post. Hopefully, the air is clearing on this.

Recently, our Tech Comm students at Mercer University have been usability testing the Department of Homeland Security’s website to help improve it. Every little bit helps.

Adopt the Digital Services Playbook

I hadn’t see this before, but the U.S. Digital Service’s Digital Services Playbook is an excellent and easy to ready resource for how to design a good service.

Everyone planning to launch a service or website should review it, whether they are a government organization or not. The U.S. Government has a lot of great resources for digital and content design (Honest!) for no charge, such as:

Get Help

Erie’s article concludes with a long list of resources for people tasked with procuring government systems. Designers and developers can use those same resources to find out where they can help out and put their expertise and passion to work.

Hidden in this list is the disappointing observation that, “Government contractors can do incredible work, but the work is typically not set up for success.” Yet she continues to offer some supportive advice, The key to getting the best out of a contract is to include usability testing and the digital service playbook in the statement of work, but also in breaking down the contract into the smallest pieces possible. 18F is doing groundbreaking work on this front and is happy to help(Emphasis mine).

Their problems are really our responsibility

In the end, it’s really up to all of us as taxpayers. Erie quotes this tweet:

I feel better knowing that there are so many ways to actually make the situation better.  Hopefully, by adopting these improvements, the improvements will get as much press (or even 1/10 the press) as the Hawaii False Alarm and it will become easier and easier to improve these vital services.

Hawaii’s alert was not the fault of a designer or operator

OK, enough with the unsolicited design updates to the Hawaii civil defense notification system, please! While the UI design of the operator’s interface could be improved, considerably, that’s not the root cause of the problem.

For those who have been in a cave for the past week, a false alarm sounded through Hawaii last weekend, which has attracted no shortage of design critique and righteous condemnation of an unquestionably atrocious user interface. The fires of that outrage only grew stronger when a screenshot of the interface was published showing the UI used (later, it turns out that this was NOT the actual UI, but a mockup).

Jared Spool describes how such an interface came into being. Prof. Robertson of the University of Hawaii also offered this detailed  outline of what likely happened. Since this post was first published, Vox posted an interview with a subject matter expert to explain how the system works in the national context.

The error was initially attributed to “Human (operator) error.” To which the UI design community (as represented on Twitter) pointed out that the system designers bear some (if not most) of the responsibility for the error by designing (or allowing) an interface that made such an error so easy.

The article linked in the NNgroup tweet observes that, “People should not be blamed for errors caused by poorly designed systems.” I hope the appropriate authorities consider this when they determine the fate and future career of the operator who made the fateful click.

While, NNgroup’s article is titled, “What the Erroneous Hawaiian Missile Alert Can Teach Us About Error Prevention,” I would argue that it is preaching to the choir and is not teaching their readers anything they don’t already know. The article describes a list of design patterns that can help make errors such as occurred in Hawaii less probable, usability 101 stuff, yet misses the elephant in the room–the overall system in which the UI exists. If context is important, and it is, the context of the system, not just that one interaction must be considered before identifying any errors to fix or placing any blame.

Here’s this armchair quarterback’s view.
Continue reading “Hawaii’s alert was not the fault of a designer or operator”

Giving criticism

It’s both easier and harder than you think, but here a few points to make it constructive.

Wait ’til your asked

Sure, you can always offer unsolicited feedback, but by waiting until you’re asked gives you the advantage of knowing what they want and that they are ready to receive it. Someone who hasn’t asked for feedback is probably not ready to hear it.

If, for some reason, you feel compelled to offer unsolicited feedback, make sure that you’re doing it for their benefit and not yours.

Understand the context

Even if you’ve been asked, understand whether someone is asking for feedback or affirmation. I tend to ask this directly, which comes of as abrupt–especially when many people don’t know for sure. A smoother way is to gains some context by asking more about the project to understand their motivations for asking.

Providing a critique when someone is seeking affirmation stings, no matter how kind and constructively you are. At the same time, an affirmation seems shallow when someone is seeking constructive criticism.

Know the goal

“What do you think?” is a common way to ask for feedback. If someone asks you this, ask them to be more specific. To give effective feedback, it helps to know how they plan to use it and how much they can change as a result. The best feedback is something that can be applied.

Be constructive and specific

If you see something that you think could be improved, be specific. It takes more time to consider and articulate, but is much more informative than vague observations and opinions.

Cite your sources

If your feedback is based on research, such as recent customer feedback, survey data, or some other research, cite it! Maybe you read or learned something the presenter hasn’t (or vice versa!).

Feelings come from you

Sometimes, you’ll see something that you can’t articulate. There are two options to take, in that case.

  1. You can wait until you figure it out.
    Sometimes it just takes time to bring your thoughts and feelings together into a coherent sentence. In that case, wait.
  2. Other times expressing how you feel is the whole point of the exercise, but speak for yourself. Unless you’ve surveyed the audience, don’t speak for them. “This makes me feel good.” or “I like how you’ve combined the text with the image.” are perfectly fine. “It looks annoying.” really means that you find it annoying, which might bear pursuing, but it is framed in the sense of “everyone will find it annoying,” which is not the case (unless, you have some research on the subject, in which case, see the previous point on sources).

If done right, providing feedback and criticism can be a win-win interaction.

Asking for criticism

Today’s Twitter gem was a Medium post from Mike Monteiro about the place for politeness in criticism–basically saying that politeness has to place in a design critique. Perhaps, but I think respect certainly has a place.

I agree with his premise that it’s “Better to get your nose bloodied in a critique of your peers, than to be slaughtered in a client’s conference room.” I disagree that a bloody nose is necessary “in a critique of [by] your peers.”

I’ll admit that I’ve delivered some of the aforementioned bloody noses–a practice that I’m working hard to reform. And, I’ve received a few, as well. In every case, the bloody nose experience wasn’t necessary, wasn’t constructive, and, in variably, was the result of just doing it wrong.

If it hurts, you’re doing it wrong, or you’re doing the wrong thing (or, you’re just out of shape).

So, how do you get constructive and effective criticism? He mentions some steps in his article that I think they bear repeating.

Get it early and get it often

Waiting until the last minute to get criticism is almost always asking for trouble. First, it’s unlikely that the designer will have time to apply any of the suggestions, so they will just be frustrating at best, and demoralizing at worst. A waste of everyone’s time, in any event, and contributing to the embarrassing experience in front of the client that he describes in the article.

It’s more constructive and effective to get frequent, small-scale, actionable feedback throughout the process, than to wait. This is not an “either or” choice, but a continuum. Nevertheless, lean towards the more frequent end of the spectrum, whenever you can.

Yes, we’re busy, but what goes around, comes around, and we’re all in this together.

Know (and state) the design scope and goal

The goal of the design might not be obvious. Likewise the scope of your involvement (and span of control) might not be obvious. To keep the criticism focused, keep the goals and scope of the design project visible.

Start by saying, for example, “I’d like you to review my redesign of the [xyz] home page to make it more accessible to an older audience. The changes include making the type easier to read, the call to action more visible, and to clarify the client’s value proposition. I’d like you to help me find aspects of the design that could be improved to meet those goals, better.”

In that, you’ve taken 60 seconds to focus the review.

The quality of answers is proportional to the quality of the questions.

If you find that you’re not getting the feedback you want, maybe you didn’t ask for the feedback you wanted. Don’t assume that everyone reviewing your work will know the goals of your design.

Thank them

A friend told me that “Feedback is a gift.” So, like anytime you receive a gift from someone, thank them!

Next up, how to give a helpful and respectful critique.

The post-hackathon hangover

Court-Whisperer-Screen-ShotHere it is, Wednesday, just four days after the hackathon and my post-hackathon hangover is finally abating. Don’t get me wrong, the hackathon was a great party. Like so many great parties, however, there’s often a morning after to get past.

Taking stock

I’ve already chronicled the experience sufficiently, so I’ll take a moment to indulge my post-hackathon hangover. This reminds me of my timer project. I’m seeing a pattern…

A demo is not a prototype

For as exciting as the hackathon was, the result was barely a protoype and, in all honesty, it was barely a demo. (It was a great pitch, though!) So, for all the accolades, there are a lot of problems that remain to be solved before the project is close to anything that could be deployed. Been there. Done that. Quite a few times, now.

That said (as the hangover fog begins to clear with the light of a new day…several days later), there were some valuable lessons to hang on to from the experience.

Less really is more

On top of our team’s focus and cooperation, I would attribute much of our success in the hackathon to our keeping the sample app and corresponding demo focused on their core values. Throughout the event, we explored various corners of additional features and context, which is good, but we also focused on the goal and used those explorations to shape the final product, not be included in the final product. Remember, the product of the hackathon is a pitch.

Less is more, until it’s less; and that’s the sweet spot.

I’m here to tell you that it is VERY DIFFICULT to throw stuff overboard to keep the ship afloat (one look into my garage will prove that point), but sinking due to an excess of good (and great) ideas, doesn’t help anyone (between you and me, building a larger garage doesn’t always help, either).

Keep your eye on the prize.

There’s a need

The positive reception to the idea we pitched shows that the idea has some legs. The audience immediately recognized the need as clear and they saw the value in the solution we presented.

The importance and significance of that  cannot be overstated. i.e.

Having a recognizable value IS HUGE!

There’s an opportunity

The post-hangover question to ask is, “how to realize the opportunity?” The solution will cost something. It’s not clear how much, though. The pitch and and overwhelmingly positive response from the audience surely will help appeal to and attract additional supporters, such as supporters, developers, designers, beta-testers, and the like. There might also be some interest in and market for a similar product in commercial applications. So..

What’s next?

That remains to be seen, but, for now, we have a website.

Some kinda fun.