The Interface Is Text [Organizing Content #23]

In my last post, The Technical Writer as an Outsider, I argued that being an outsider to a project gives you a valuable perspective about the gaps, problems, inconsistencies, and other issues in an interface, so you can do a better job documenting it for other outsiders.

After writing the post, I tried to embrace the outsider mindset and hunker down at my desk to go about my work. Working under this metaphor, I realized that I was no longer moving toward a solution, but merely providing documentation to address something others had already created. I felt a sense of emptiness and lack of purpose.

One of my colleagues, Derek, shared with me a new metaphor he recently adopted to describe technical writing. He had a bitter experience on his first project in our organization when one of the project managers told him the tech writer’s role is to document “what is, not to suggest what should be.” Now Derek has come to think about technical writing as a kind of janitorial job. He said,

At the end of the day, we’re really janitors. I know it may sound derogatory and even offensive, but our job is to clean up other people’s messes. Project managers don’t want to see us, they don’t want to interact with us. They just want us to arrive after the work is done; they want us to come in and do our jobs quietly, cleaning up the spills, vacuuming the crumbs, taking out the trash — all without complaint or objection.

Such a mindset is not only uninspiring, any writer with a keen eye for language and a good analytical mind will be unfulfilled in such a role, and Derek knows it. Playing the janitor, acting as an outsider, or as  Gryponmountain puts it, playing the monk in LadyHawke whose job it is to describe the broken stairs and other areas of decay and hazard in an old decrepit cathedral, will lead the once-aspiring technical writer to burn out and seek another career. At our core is the drive to create, not to clean up.

But there’s another dimension to this problem, and it’s a more important one. Putting aside all resentment about playing a janitorial role, language experts should play a more active role in shaping the interface because the interface is text. As such, writers do a disservice to project teams if they don’t play a role to help clarify and sharpen the interface language.

Of course the interface also has a good bit of graphics and design, but largely what users interact with is text. This assertion is most striking when you actually remove the text from the interface you’re using. For example, here’s the text removed from the WordPress interface.

The WordPress interface with all text removed

The WordPress interface with all text removed

Go ahead and create a new post, timestamping it to be published next Monday, add a category and change the author. What, you can’t do that? You could probably still format the content with the rich text editor’s buttons, but what kind of content are you creating — a page, a post, or something else? And what is that pushpin at the top doing?

Here’s the text removed from the Snagit interface.

Snagit with all interface text removed

The Snagit interface with all interface text removed

Go ahead and create a menu delay capture, add a border around it, and set the default file type to be PNG and stored in the D:// drive. Again, it’s difficult to do this without text, and only possible if you already know the application.

Here’s the text removed from the Youtube admin interface.

The Youtube interface with no text

The Youtube interface with no text

Upload a new video and tag it with your website title, and then select to play it in HD with captions. Again, it’s impossible to do much of anything in the design itself, as simple as the interfaces are in each of these examples. The user needs to the text to navigate and understand the interface.

What Kind of Writing Is Interface Text?

Writers are often skilled in all types of language forms, from short poems to letters to essays to how-to text. But the text on an interface is a different kind of text. If you isolate the text from the design elements, you lose a lot of the meaning, similar to what happens when you remove the text from the design.

The design adds meaning to the words. When designers choose a typeface for the text, it adds meaning. The hierarchy, the position on the page, the background color, the bold or italic formatting, the relationships and proximity to other elements, the length of text, the text’s placement in the user’s line of vision, the accompaniment of icons — all of these design elements give context to the text, so that you’re no longer just playing with words and deciding on the right word. You’re trying to find the right word in the right context.

The Challenges of Word Choice

Designers attempt to add meaning through design elements, but the greatest challenge designers and project managers face in interface text is probably word choice. How many times have you seen a word used in an interface you’re documenting that just doesn’t seem to fit? Users need to reconcile a banking statement. Committee members can submit a linked item. Building schedulers can allocate resources. To stop spam you activate Akismet. Bloggers can burn a feed. Analysts can drill down into the data. Content managers can configure the slug for each URL. When you upload an image, the message you see says Crunching. In every instance, the word choice is probably wrong. It doesn’t communicate plain understanding to the user.

In addition to the wrong word, other times the problem is inconsistency. When you finish making edits, you Save / Submit Changes / Commit. If you don’t want to save your changes, you can Cancel / Discard / Go Back. To set up a recurring series in a calendar, you can choose to set up a repeating event, and later you can edit the recurring event.

Finding the right word for the context is a skill. It often involves discovering the language of your users — through interviews, observations, or other feedback — rather than sitting in a project meeting and reasoning it out.

In an upcoming post I’ll dive into more principles for interface text. But my overall point here is that the interface consists mainly of text, and because of this, writers (language experts) need to help shape and craft this interface language.

You can’t influence the interface text if you’re brought on to the project team one month before it’s released. By that time, quality assurance engineers are already running their regression testing and preparing to hand it off to infrastructure for release. Developers have already used the same terms on multiple screens, dialog boxes, error messages, database tables, and throughout the application code. Unless there’s a major problem with the words, no one will be inclined to change them. The project manager sees no pressing need to make language changes so late in the game, because everything seems to be working just fine prior to release. No customers have complained yet, so it’s easiest to leave it alone.

Some Research Supporting Early Involvement of Writers

If you want to insert yourself early on the design process, the first step is to believe that you belong there. You are a word expert. The interface is full of words. In Text Treatment and User Interface,  Tobias Komischke notes,

Before graphic user interfaces, text was the primary means of both input and output defining human-computer interactions. Even today, much of the information user interfaces present is textual. Therefore, we should notunderestimate how the right text treatment can measurably improve user productivity and increase user satisfaction.

In other words, when interaction designers present their prototypes for the new application interface, they’re not just presenting a design. They’re working with words and designing text with meaning in everything from buttons, labels, page titles, error messages, dialog boxes, tabs, drop-down boxes, notes, and other interface text. Writers should be present during the design meetings. We understand the nuances of language more than any other project team member.

In Art and the Zen of Web Sites, Tony Karp says,

In a successful advertisement it’s the graphics that grab you,  but it’s the text that does the selling.

While designers would disagree that graphics only catch your attention, certainly almost no one can get by without text. The user interface becomes incomprehensible. But you can still often get by even if you strip out the stylesheet and images.

Apple, the king of intuitive interface design, stresses the importance of clear, consistent text and recommends including a writer  in the development process. The Apple Human Interface Guidelines state:

Although Mac OS X uses graphics as a primary means of user-computer interaction, text is prevalent throughout the interface for such things as button names, pop-up menu labels, dialog messages, and onscreen help. Using text consistently and clearly is a critical component of interface design.

Your product development team should include a skilled writer who is responsible for reviewing all user-visible onscreen text as well the instructional documentation. The writer should refer to the Apple Publications Style Guide for guidance on Apple-specific terminology.

Is text a “critical component of interface design”? Of course. Take the text away and the user can do nothing. Involving the writer early to get the text right can make a huge impact on usability.

The Microsoft Developer library also encourages involving the writer early on in the design process. In an entry on User Interface Text, the Microsoft authors say:

Software developers often think of text as relegated to product documentation and technical support. “First we’ll write the code, and then we’ll hire someone to help us explain what we have developed.” Yet in reality, important text is written earlier in the process, as the UI is conceived and coded. This text is, after all, seen more frequently and by more people than perhaps any other type of technical writing.

Comprehensible text is crucial to effective UI. Professional writers and editors should work with software developers on UI text as an integral part of the design process. Have them work on text early because text problems often reveal design problems. If your team has trouble explaining a design, quite often it is the design, not the explanation, that needs improving.

I find it reassuring that the two biggest companies in software, Apple and Microsoft, both recommend involving the writer early in the development process to shape the language of the user interface.

Regardless of what companies and style guides recommend, writers will need to prove their worth to earn a seat at the table. As such, writers will need to be familiar with best practices for including text in the interface. In my next post, I will explore best practices for adding interface text.

Adobe RobohelpMadcap Flare

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

14 thoughts on “The Interface Is Text [Organizing Content #23]

  1. Patty Blount

    Tom, I think you’ve made some excellent points here. The first image of the WordPress site without its text really drove them home for me.

    Great post. I’ve forwarded the link to my whole team.

  2. Ben M

    A couple of points you mention that stand out to me:

    • The Apple dev guide emphasizes the importance of UI text. Since our designers are big Apple fans, maybe we ought to point out to them that Apple strongly recommends this process.
    • Microsoft’s statement that the UI text = technical writing. I have thought of it as instructional text and therefore falling into our purview, but this makes me think about it more. If we can show dev teams how the UI text IS technical writing, then we can take ownership of it. Within the last few weeks, I’ve had developers coming to me more and more to get good wording of UI text, modal messages, and error messages, but it has taken working in the same project portfolio for a few years to get here. And notice that it’s the developers, not the designer (we have a newer one who probably doesn’t have experience working with a tech writer on UI text). I have had designers come to me with text requests before, though.

    The monk’s warning from LadyHawke rings in my ears: “Walk on the left side!”

  3. Julio Vazquez

    Awesome post, Tom.

    I wish all software companies would read just this single post to see how important the text on their interfaces is. There are many companies that do not involve their technical communicators in the design process and wind up paying the price later in their production process. The same companies also don’t realize that changing the interface, after their customers have become familiar with the quirks an inconsistencies, also leads to dissatisfaction. Put the product out with poor interfaces and it’ll be more costly to fix it later.

    Great thoughts!

  4. John Hewitt

    “I realized that I was no longer moving toward a solution, but merely providing documentation to address something others had already created. I felt a sense of emptiness and lack of purpose.”

    And on this day, Tom finally, truly became a technical writer.

  5. Fred Sampson

    For the last 2 years, at least 2/3 of my work has been on what we call embedded assistance: all of the text in the UI, plus the linked help. Only if we can’t give the user all the information that they need in the UI do we write help topics. I own every word that appears in the UI, and I edit the source files directly. I work closely with the development and UX teams to make it all work; it’s part of our process.

  6. Scott

    My company uses the Scrum agile methodology to develop software, and is very good at incorporating documentation team members through the whole process. Since I began working here, I have been very impressed with how well it works, especially compared with some of my disconnected experiences doing documentation for some of the LDS Church’s applications while at BYU.

    In the monthly project planning meeting I am included and valued as a member of the team with just as much input and weight as the developers, QA, and Business Intelligence.

    I am expected to plan the documentation needs of the project and maintain communication with team members throughout the sprint. My team members look to me for decisions on UI issues, wording of error messages and UI titles, and they rely on me to make sure everything they are doing is explained, validated, and advertised in the documentation.

    They realize that the cool features they are working on may never even be used by anyone unless they are highlighted and explained well in the documentation. One developer said “We need Documentation to make what we do look GOOD to the customer.”

    1. Larry Kunz

      Scott, I’m glad you mentioned Agile. One of the real strengths of Agile is that the technical writer is right there in the room when the details of the UI are being developed. This assumes, of course, that the technical writer is “included and valued,” as you were — and as is the case on most Agile projects I’ve encountered.

      Tom….This is one of your best articles yet! As Julio said earlier, I wish that everyone in software development could read it. The screenshots without text were brilliant.

  7. Rengaraman

    It’s a fantastic idea to include TWs’ in the UI design much earlier. But I am afraid not many project managers do encourage this. Still they believe that UI is something linked with the development environment.

  8. Pingback: Technical Communication: The QA of Product Design | Gryphon Mountain Journals

  9. Richard Rabil, Jr.

    Great post, Tom. I love the pictures and really like your observation on the difference between traditional print-based text and interface text.

    Also, one of your quotes — “In a successful advertisement it’s the graphics that grab you, but it’s the text that does the selling” — reminds me of Donald Norman’s stress on the three dimensions of design: visceral (what’s your first impression?), behavioral (is it usable and does it really meet your needs?), and reflective (is your memory of the product positive?). Ideally, product teams will fulfill all three dimensions very well. When it comes to the computer interface, I don’t see how you can be successful in each dimension without, as you argue, understanding the interface as text.

  10. Pingback: How to Get Programmers to Change User Interfaces | I'd Rather Be Writing

  11. Pingback: How to Get Programmers to Change User Interfaces » eHow TO...

  12. relationships

    This design is incredible! You most certainly know how to keep a
    reader amused. Between your wit and your videos, I was almost moved to start my own blog (well,
    almost…HaHa!) Great job. I really enjoyed what you had to say,
    and more than that, how you presented it. Too cool!


Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>