Any product that needs a manual to work is broken. (Elon Musk)

A user interface is like a joke. If you have to explain it, it’s not that good. (Half the internet)

You’ve probably seen one or both of these quotes circulating at some point. They’ve both had vast appeal. And they sound true, don’t they? I’ve seen them shared by plenty of tech industry people, and I have to admit that this makes me both a little sad and a little mad.

It seems quite a few companies have bought into the idea that their products are so simple and brilliant that no docs are required. This is true for almost none of them.

Most products without documentation are not works of genius, they’re just systems that are harder to use than necessary. A complicated user interface can actually be very good once you’ve learned it—just ask any geek who swears by the command line.

If you don’t have proper, public, searchable product documentation, it’s time you started.

Here are 7 reasons why.

1. Solid Documentation Makes Everyone’s Lives Easier

If you don’t have public product documentation, I am willing to bet you have a lot of unofficial documentation floating around your various departments.

This internal documentation comes in various formats, and different people will hold on to different versions of the same document without knowing other versions exist. Customer support will struggle to get the information they need about the product. They will also piece together their own documentation based on what they hear and find. They may or may not share that documentation with customers.

Everyone will benefit from having a proper documentation process, even internally.

I believe tech writers should be embedded in development teams if at all doable. They should also stay close to User Experience and Customer Support. Their documentation will not come out as marketing documents, elearning, webinar presentations, or scripts for customer support.

What this documentation can do, is:

• Act as a reference point and source of truth for almost everything else you want to produce.
• Help with internal alignment and lessen the risk of people further removed from product development guessing or making stuff up.
• Simplify onboarding for new employees or employees transitioning to new roles.

In the age of “content”, there is much talk of making the most of the content you have, repurposing and publishing across channels. Documentation is an excellent and natural starting point.

If you get into DITA or other structured data formats, you can even repurpose content directly. I have yet to drink the DITA kool-aid, but would love to see more easily accessible systems for single-sourcing.

2. People Need Searchable, Scannable, Skimmable Text

Video and webinars may be popular, but when you need to perform a procedure you only do once in a blue moon and have never fully memorized, you probably want a scannable, written procedure with steps in it.

While working with elearning, I once saw a colleague save a series of screenshots from an elearning sequence so that they could recap the steps on demand without sitting through the course. Even elearning pros don’t  like it that much.

It’s also not enough to put guidance inside your user interface. The most brilliant explanation next to a setting will do me no good if I do not know where to find that setting (or why I should look for it in the first place).

I have recently spent a lot of time with Odoo, an ERP system that also does CRM, ecommerce, and a bunch of other stuff. For a system that does so much—and rather well, most of the time—it has a shockingly small amount of product documentation.

Instead they have chosen to create “setup wizards” in their interface. These wizards contain mostly general project and marketing guidance and very few instructions on setting up the software itself. They must have spent massive amounts of time pouring tons of this irrelevant text into their user interface. They also provide elearning videos on some topics, and some very brief user documents, and that’s about it. (Their developer documentation looks a lot better, although I’m not the best judge of that.)

I have spent countless hours searching in vain for basic configuration guidance and having discussions with consultants and customer support who also don’t have documentation to refer to. And I am convinced everyone’s time could have been so much better spent.

3. Text Is The Easiest Format to Maintain

One theory I heard from a consultant about why this company had so little documentation, was that it would be hard to maintain, and that’s an argument I hear quite a bit about documentation.

Having maintained all of the above-mentioned genres at some point, I can safely say that yes, maintaining a large documentation set is indeed a lot of work. But properly version controlled, text-based documentation is far easier and cleaner to maintain than elearning, videos, and elaborate in-product wizards, especially for a complex product.

Don’t use “it will be hell to maintain” as an excuse not to document your product.  Use it as motivation to start your documentation off right:

• Pick a sensible, text-based source format (yes, this leaves out MS Word) and version control everything.
• Hire an experienced technical editor / writer to own the docs and the process as soon as you can afford to.
• Don’t outsource any of this unless you actually do want a maintenance nightmare.

4. Having A Documentation Process Will Improve Your Product

Here’s a tech aphorism I prefer to the manual jokes: If I can’t document it, people can’t use it.

Tech writers tend to team up well with Quality Assurance, for several reasons. For one, most QA people have fabulous product knowledge. Also, good tech writers poke holes, report bugs, and play user advocate, much like good QA people.

Having to document flows and procedures in full can be a very effective way of highlighting shortcomings and over-engineering. (I remember saying “are you sure you want to have three separate tools for this migration process?” and, fortunately, being heard.)

5. Your (Power) Users Will Love You For It

Leah Guren of Cow TC, who I’ve had the pleasure of listening to on several occasions, is one of few who has done usability studies specifically on documentation.

Guren found that the typical “amateur” user assumes that documentation exists, and that it is pretty much perfect. However, there is almost nothing in this world that can make them voluntarily turn to the help documentation.

Advanced users, on the other hand, would use and rely on documentation, and would be willing to leave a vendor if their documentation wasn’t up to snuff.

6. They May Even Help You

I actually asked my contact at Odoo where I could sign up to help with their documentation … I know I am not in the least typical, and most users are not current or former tech writers, but if you have a user base, by all means solicit participation.

By gathering feedback and analytics on product documentation you will also get new information about the needs, questions, and frustration points of your users.

7. Ultimately, It’s Your Job

Administration of several complex systems is part of my current job. I am constantly looking things up, and nothing makes me happier than finding up to date, official documentation that meets my needs.

By all means, I will be happy with a thread on a forum when it actually answers my question. But if you’re a product vendor—why on earth would you leave it up to random people on third party sites to make sure your users know how to use your product?

Proper product documentation is your job, dammit.

The post 7 Reasons to Start Publically Documenting Your Product appeared first on andedam.org.

I’m A Writer, Not A Jeopardy Contestant

When you write for an FAQ, you take out the fun factor and big prizes, but keep the stilted and awkward aspect. No matter the topic, you have to turn everything into a question.

I will take most format challenges anytime: I write text for graphical user interfaces, I follow patterns when documenting procedures, I tweet. Then again, those are all exercises in conciseness, and I love concise, especially in technical communications.

The frequently asked questions format seems concise enough; an FAQ section is usually built up of small, discrete topics.

But in my experience, the opposite is true. From both a writing and reading point of view, I find FAQs to be contrived, redundant, and inefficient.

And that is why FAQs must die.

The UK Government Digital Service has made a fantastic case against the format in FAQs: why we don’t have them.

1. The FAQ Format Is Contrived

The biggest FAQ I ever worked on was a poorly defined database of articles meant to cover everything people couldn’t find in the general documentation. Yes, I admit it had plenty of issues alongside the question format.

The writing team had previously agreed upon an FAQ format, but many of the best entries still had titles that were scenarios, as these articles were often written for troubleshooting purposes.

Imaginary example: “My client times out when trying to connect to the load balancer.”

A helpful colleague, realizing that these couldn’t be read as questions, decided to go through the whole thing. At each scenario, they would toss in full stops and a “Why?” at the end to fit the format where needed.

“My client times out when trying to connect to the load balancer. Why?”

Every time I saw one of those titles, the “why” would take on this whiny, accusatory tone in my mind. It may not have read very well, but my colleague was doing the right thing entirely, both for the sake of consistency and for demonstrating the shortcomings of the format.

In the end, we agreed that we would call it a knowledge base rather than an FAQ and drop the question requirement. We even got a few other publishing guidelines implemented.

By all means, create a knowledge base if you need one, but define it well and don’t force a question format.

2. FAQ Headings Are Redundant And Unscannable

When you turn headings into questions, you add filler words, and you mostly lose the opportunity to frontload—putting the most significant words, the keywords users are actually looking for, first.

The same thing goes for “how to”-style titles, even when there is not a question mark at the end.

To see what a poor idea this is, try listing several of these headings after each other as they would be in search results or an index. What you get is a list that has low scannability and lots of redundancy, which is not what anyone wants in a list. (I have written about the value of scannable lists before, in Making a list? Check it (at least) twice!)

3. FAQs Are Not Efficient Communication

Why make people look for the question?

If you know the questions people are asking and at which point when interacting with your product, website, or company, then you can probably reassure them without asking the question out loud for them.

The important thing is making sure the information they need is available at the right time.

As an example: The question I most often ask myself as a visitor to non-Norwegian ecommerce sites, is whether they ship to Norway. Finding out usually requires digging through shipping policies or, in some cases, going through most of the checkout process until getting to a dropdown without my home country in it.

Surprisingly recently (it’s not like the technology is new), more sites have started using IP address sniffing for good. I am thrilled when a site displays a small info banner the moment I access their site, stating whether they ship to my country of residence. THIS is what I want: information before I waste my time.

The FAQ format is inefficient. It’s not the question people are looking for. The nature of FAQ headings also often leads to having five tiny articles or sections where one slightly longer writeup would have been sufficient.

Content strategist Hilary Marsh has some great examples and does a terrific job of explaining Why FAQs are not effective web content.

FAQs Won’t Just Go Away. Why?

The UK Government Digital Service wrote FAQs: why we don’t have them in 2013.

I had hoped that by now, with increased focus on usability, scannability, and search engine optimization through keyword frontloading, that new products might start avoiding the FAQ format.

Still, I keep hearing “and then we’re going to need an FAQ”. My suspicion is that:

• “FAQ” has become shorthand for either “bite-sized information” or even “searchable documentation”.
• Most people wouldn’t bat an eye if they clicked on “FAQ” and found a knowledge base without question marks in the headings. As a writer, I may obsess over genres, but I know that most readers don’t. Neither do the managers that tend to bring up the requirement.

As for search engine optimization, the pendulum swings. Many search engine optimizers are adding more questions to their content in attempts to get into Google’s featured snippets, the “answer box” displayed above all the other search results.

The sad thing here is that Google’s logic for picking answers seems primarily focused on the question and its exact wording. The quality or accuracy of the answer appear secondary, demonstrating again that the question really isn’t what the user is looking for. The logic needs to become a lot more sophisticated, and I assume it will.

How To Kill An FAQ

Over the years, I have v e r y slowly worked my way up from growling “NO!” and sharing that link from gov.uk the moment someone mentions “and we need an FAQ”.

Now, I’ll let at least a few seconds pass! I might not even speak the words “FAQs must die”.

On a good day, the cool, calm, and collected answer is: “Of course we need to make sure we are answering people’s questions.” Or even, if you know the scope is significant, “Sure, we’ll need some sort of knowledge base”. And then “What are the questions people are asking, and when? Do we know, or do we need to start finding out?”

You should be the one looking for questions, not your reader.

And if you can answer before they even think to ask, the FAQ is well and truly dead.

#faqsmustdie

The post No, You Don’t Need An FAQ. FAQs Must Die. appeared first on andedam.org.

And yet, I’m here to tell you–with enthusiasm!–about a set of tools and techniques that can work wonders for your writing. I have come to use several of these tools on a regular basis myself.

Used the right way, these tools will help you get your message across in a crisper language that is easier to read.

1. Let Hemingway pick it apart

I’ve written about the Hemingway app before. This app got me started using more automated analysis. Hemingway takes you to task for such offenses as:

• Hard-to-read sentences
• Too many adverbs
• Use of the passive voice
• Difficult words that have simple synonyms

You can use Hemingway directly in the browser. I first wrote this blog post in the Hemingway desktop app, which has some nice perks. You can save and load files, export them to HTML, and turn editing mode on and off. Seeing all that highlighting while typing can be disruptive. This setting lets you think with your fingers first and do the editing later. There’s also support for Markdown.

(For more on how Hemingway works, see my first review of this tool, Your own, personal Hemingway.)

2. Find your Flesch-Kincaid score

The Flesch-Kincaid scale for reading ease is one of the most well-known readability calculations for US English. It’s also the one I choose to look to, although there are many others, mostly because my previous employer used it, and one can only relate to so many scales.

Flesch-Kincaid is more fine-grained than for example the Hemingway readability grade:

• 90–100: easily understood by an average 11-year-old student
• 60–70: easily understood by 13- to 15-year-old students
• 0–30: best understood by university graduates

(Source: Wikipedia)

This makes it easier to track readability improvement of longer documents, which Hemingway in the browser is not so well suited for.

If your writing tool of choice does not have this built in, the easiest workflow is to simply copy/paste the output into readability-score.com.

Oh, and if you’re in documentation, make sure to remove any legal disclaimers you’re stuck with from the text before analyzing it. Their profound lack of readability is probably out of your hands.

3. Use built-in readability tools

Of course, it is easier when testing or analysis is built into the writing tools you already use. This blog uses the Yoast SEO plugin, which includes a readability analysis based in part on the Flesch-Kincaid scale.

If your writing tool of choice (or duty) is Microsoft Word, it can also test your readability for you, but beware:

Depending on your version of Word, not only may Word force you to check your spelling and grammar first, it will warn you that it resets your grammar and spell checkers to do so.

So you may prefer to use an external tool after all. If you want to have a go, try these instructions for setting up readability checks in Word.

4. Check your sentence length

Long sentences are proper readability thieves. If you use Word or readability-score.com, they can both calculate your average sentence length.

The average won’t identify the outliers, of course, for that you need something like Hemingway.

For a good read on sentence length, see this post from gov.uk: Sentence length: why 25 words is our limit.

5. Track and compare your readability

It’s worth noting that you will want to find a readability calculator you like and stick with the same one over time. Different tools use different algorithms, even to calculate scores on the same scale.

When you have ensured comparable results, start comparing! Accumulate your own readability statistics. I’ve used a simple spreadsheet. You can track and compare revisions of the same document over time, or compare different documents to ensure a consistent readability level.

Good trends, bad trends, consistency, it will all be easy to see and act on as required.

The blog post Write Better: Online Readability Testing Tools Compared shows how different results tools produce for the same piece of text.

The best editors and proofreaders remain human

Of course, these tools and tricks won’t re-structure your entire document or tell you that your blog post is at least twice the length it needs to be. Or that your jokes just aren’t funny. For that, you need an editor, a proofreader, or at least an honest friend or colleague.

I do find that having self-editing tools to help me spot the low-level issues makes it easier to spend time on those other factors, though.

And here’s a bonus “tool”: Time. If you have to be your own editor, give yourself a little time and distance from your text before re-reading and polishing if at all possible.

Do you have any experience with self-editing tools and techniques? Share your tips and hard-earned lessons in the comments!

The post The Helpful Machine: 5 Self-Editing Tools to Improve Your Writing appeared first on andedam.org.

Today, you sent me a message that pushed me over the edge after a blogging hiatus that has been far longer than I like to think about.

Subject line: “Was it something we did?”

Body: I have no idea, do you honestly think I opened that? The message was clearly based on some pre-configured logic catching users who signed up for your service eons ago, then stopped using it. I’ve tested a lot of services for work in the past year, most of which I’ve left behind. It was less something you did and more something we didn’t.

But why oh why would you think it’s appropriate, funny, cute, or *shudder* engaging to sound like a needy ex-partner?

AWKWARD!

Today’s overly attached subject line was not an isolated incident, of course. Just a handful of fairly recent examples from my inbox:

• A subject line welcoming me to the [service] family, message starting with “Hey, you’re awesome!!”
• A “thank you for upgrading to a pro account” message signed “Your friends at [company]”
• A service sign-up response with the subject line “Friend, welcome to [service]”

All sent, of course, by [Firstname] at [Company] — a trick so ubiquitous it no longer stands out in the least in the increasingly crowded Promos section of my Google Inbox.

Most of my personal and even work messages now go through chat, but everyone and their grandmother’s company is bombarding me with email as a lead or customer — “drip campaigns”, auto-responders and quasi-personal messages intended to steer me along the journey to conversion from lead to customer, and from customer to evangelist.

But I must admit, [Firstname] at [Company], it’s increasingly rare that I even open your messages. And you just seem to get chummier and chummier.

I expect your company does a lot of A/B testing, so please do tell me: Does the bromance lingo actually work on a majority of your targets? Because to me, really, very little could be more alienating.

It may have to do with regional culture, it may have to do with being too old to be part of the main target group for Every Marketing Campaign on Earth — millennials — but honestly, even a few millennials have mortgages and PTA duties and the odd gray hair and cellulite at this point, are you really sure they don’t prefer being talked to like grownups?

And for those who would be on board with the “you’re awesome double exclamation mark” thing amongst actual friends, are you sure they don’t see you as something of a wannabe, or like the awkward parent who picked up a little bit of slang 10 years ago and still thinks it’s the bomb?

Why Can’t We Be Friends?

One of the reasons I’m ranting about this is that since going from tech writer at a massive corporation to information architect at a small company where everyone wears a rich selection of hats, technical marketing for the business-to-business market is a form of communication I’ve suddenly had to care about. I’ve been reading up. And I’ve despaired, discovering that “landing pages” does not actually describe pages for visitors to land on, but pages for businesses to land people’s email addresses.

After reading a few more marketing blog posts than was clearly good for me, a bit too much of it started to make sense. Then, thankfully, I was lucky enough to spend most of last week at the Information Architecture Summit, an amazing conference about IA and user experience, whose theme this year was inclusion and “a broader panorama”. What happens when we put people at the center, when we design inclusive experiences, when we genuinely care about the humanity of every user, visitor, customer? And I came back reassured that what doesn’t happen is shiny happy auto-responders holding hands. (I learned a bunch of other stuff, too. There will be more blogging.)

So no, it’s not that I don’t think that businesses can have interesting information to share with (potential) customers by automated email, or that customers and vendors cannot have a friendly tone when they know each other — on the contrary. But here’s the thing, [Firstname] at [Company], the two are entirely separate things. And because you are not a person, but a set of merging and mailing rules, that is something you will never understand.

And that is why we can’t be friends. So can you please drop the act?

Not exactly yours,

Jorunn

The post Dear [Firstname] at [Company] — Drop the Fake Friend Act appeared first on andedam.org.

• Ten Reasons Developers Hate Your API (and what to do about it). Some great take-aways for anyone involved with APIs and their documentation here. And yes, terrible documentation is reason number 1 on the list.
• To cut resource-draining just-in-case material: Put each topic on trial. I have a couple of other tools in my belt for this already, but more are always handy. Similar to the 5 whys of root cause analysis.
• Survey on technical communications in Europe. Not so much a general survey as an attempt to figure out what the market would be for tekom activities in your country, but being from a country with barely any sort of relevant conference and training activity, I’m all for that.
• If you want them to RTFM …. Thinking this would make a good motivational poster for tech writers. Maybe even a t-shirt?
• Speaking of t-shirts, I want this one:

  

The post Link Roundup: APIs and Fine Manuals appeared first on andedam.org.

Here are the three most common unhelpful types of error messages that I know of, and what makes them unbearably annoying to me.

1. Written for the developers: Object reference not set to an instance of an object

Of all error messages that should not go out to end users, this example is probably my least favorite. Someone really should just change the standard nullpointerexception error with something more readable to a user, once and for all. “Developer malfunction”, perhaps. I kid, but only just. And there are many more messages that follow a similar logic.

All too often, internal error messages trickle out to users from frameworks, APIs, or deep dark places in code that nobody every intended to expose. They are usually hardcoded and hold no information that the user can make sense of, or wrap a tiny piece of readable information in noise. Typically, they also use words like “illegal”, making any normal person think a crime has been committed, rather than the use of a character that couldn’t be parsed.

2. Well, duh: Unexpected error

Ohhhh, so you didn’t see this one coming, application? Well, that’s helpful for me as a user to know. And now what?

The literal “Unexpected error” is quite common, but there are tons of messages out there that are at about the same level of helpfulness once you’ve read them. Telling the user at least something they don’t already know is a very basic criterion for an error message. And they probably don’t care whether or not you were expecting it, but they do care whether it will fix itself or requires intervention.

3. Intended to be funny: Well, this is embarrassing

The example is from Firefox being unable to open a page, but Chrome’s “He’s dead, Jim”, or the Twitter whale, are more of the same, and the trend has been spreading, perhaps due to advice like this post from UXmas: The 4 H’s of Writing Error Messages, where “humorous” is one of the H’s, as the author claims it helps diffuse frustration. I disagree–and actually even the UXmas author himself goes on to warn that humor is not appropriate in most actual error situations.

Cutesy, chummy, intended-to-be-funny error messages may serve that purpose the first time the users see them. But error situations have a way of repeating themselves. The tenth time you get to the same error, the funny, “friendly”, conversational error message style is likely to have grown on you much like a fungus. There’s a reason there are tutorials for Getting Rid Of Firefox’s “Well, This Is Embarrassing” Message.

Being helpful is about being respectful to the user. Error messages should be troubleshooting assistants for users, not their pals. An actual pal might buy the user a drink when the operation fails for the 15th time, the error message will still just say the same thing.

Helpful error messages are hard (to write)

Users are annoyed when something fails. We don’t want to feel like we did something wrong, or like we spent our time, money, or both on a product or service that isn’t up to the job.

Writing helpful error messages is hard, but probably one of the best possible uses of a technical communicator’s time.

Which error messages are most annoying to you? Do you enjoy the use of humor?

The post The Three Most Annoying And Least Helpful Types Of Error Messages appeared first on andedam.org.

A well-written list can be a quick read, but when making a list, taking some time to properly consider the format and syntax will pay off in clarity and helpfulness for your readers.

Below, I have gathered some advice for writers and editors dealing with lists, based on my own writing and editing experience. If you have other tips or pitfalls on your mind, please share them in the comments!

Use The Right Kind Of List

It’s easy to think that usage conventions for list types are exactly the kind of thing only writers would care about. If you think that way–I have myself on occasion–then consider this progress screenshot from a WordPress backup plugin that I recently installed:

Without reading this multiple times, would you feel certain that you were actually not supposed to do anything mentioned in this numbered list? The introduction says one thing, but the choice of list type is communicating something different entirely.

Use an ordered list if you are describing any of the following:

• a procedure to follow
• a sequence of events to observe
• a clearly prioritized order

Some may also prefer alphabetical ordered lists for options where only one may be selected (“Do one of the following: a. b. c. d.”).

If the list is not a sequence, an unordered bullet list is the most common option. However, long bullet lists are not particularly easy to read. For lists that are long and/or include a lot of information in each list item, these two other options are worth considering:

• description lists (definition lists pre-HTML5) for glossaries, metadata listings, and similar. These tend to be styled in a manner that make them a lot more scannable than bullet lists. See Mozilla Developer Network for a good description and examples.
• tables. I know, tables are not actually lists, nor do they have the Twitter or Pinterest appeal of a Top 5 list, but for reference-style material, a table provides much better findability and overview than a bullet list.

I like lists, I’m controlling, I like order. I’m difficult on every level. (Sandra Bullock)

Avoid Redundancy

List items that start identically, or semi-identically, reduce scannability. Keep in mind that tables of contents are also lists. If you have a table of content that is generated based on your headings, considering each heading a list item is useful.

To ensure list items remain scannable, you can:

• front load each list item by starting with important keywords that set it apart from other list items rather than something generic , such as “You will need to …” or “For simplicity and ease of use, we have …”.
• move repetitive phrases outside of the list itself. For example, instead of starting each list item with “how to”, make “how to” part of the introductory phrase that comes before the list.
• drop any words and expressions that don’t add to the meaning. In most cases, list items don’t need to be complete sentences.

As a bonus, if your writing will be translated, you’ll save money by avoiding redundancy.

Every morning I get up and look through the Forbes list of the richest people in America. If I’m not there, I go to work. (Robert Orben)

Be Consistent

In a list, each item should have a similar syntax. This is a pet peeve that probably annoys me as a writer more than most readers, but I have seen plenty of bullet lists that would be confusing for any kind of reader.

Before unleashing a bullet list on the world, read through it starting with the introductory phrase and check that all list items:

• start in a similar fashion to the others and read as a grammatically correct continuation of the introductory phrase. If the introduction says: “This chapter will tell you how to:”, you cannot have list items starting with “making” or “configuration”.
• share the same grammatical subject or state their subject clearly. Otherwise you may easily conflate, for example, something done automatically by software with something  users must do themselves, or something the software vendor can do for you upon request. In my experience, this problem is not uncommon in lists of features and software specifications.
• use similar syntax and punctuation. Mixing questions with statements in the same list will usually not read well. Whether or not to end each list item with a full stop is a style/preference issue. It is also painfully hard to remember and follow up on in a consistent manner.

We like lists because we don’t want to die. (Umberto Eco)

The post Making A List? Check It (At Least) Twice! appeared first on andedam.org.

Everybody fails (sometimes)

But every. Product. Fails. Networks happen, unexpected input happens, integrations with other products happen. The real world happens, and what do we do then?

My last post about unhelpful error messages sparked some interesting comments and discussion, on the blog and in the Technical Writer in Action LinkedIn group, including a lot of good points about what fellow tech writers consider to be good qualities in an error message. I said I would follow up my post with a more constructive take, and here it is.

1. Fight the power (push back, fix the code)

Rewriting error messages often runs the risk of being lipstick on the proverbial pig. Sometimes it’s all we can do as writers short term to improve the writing, but we shouldn’t be scared to push back and look at whether the product is behaving as it should in the first place:

• Could the error be prevented before it happens? For example, improve the UI to prevent users from entering invalid input, highlight required fields, and so on.
• Is the error displayed to the right users? Misconfiguration in the backend should raise a ticket for whoever configures the backend, rather than cause ugly error messages for the end user who can do nothing about it. Messages that essentially say “Contact your administrator” should rather say “Your administrator has been contacted”.
• Is one error message enough? One of my most frequent requests is actually more error messages. For users, more messages can actually be a good thing, because they allow us to be more specific. Too often, developers create catchall messages that cover so many scenarios it is close to impossible to give users instructions of any value. A shocking amount of error messages can be paraphrased as: “This, that, or the other may have happened. Try 547 different configuration changes, or wait an hour or two and it may have gone away.” Not helpful.

2. Find out what it means to me (respect the user, be instructive)

Good error messages are respectful of users and their time. Conciseness is a value in and of itself. Users read this stuff to do, they don’t read to learn. For this reason, I find that going into detail on exactly what has happened is often not the best use of screen space and user attention.

For the user to be able to do, the message must be instructive. An instructive message focuses on why the user should care about this message, and either give them reassurance that someone else will fix the problem, or give them the information they need to act themselves.

This information needs to be:

• specific
• inclusive enough that it doesn’t entirely exclude potential scenarios. Few things are more frustrating than following instructions that turn out to have no relevance.

When working on pop-up messages, I always try to pay attention to the buttons as well, and aim for descriptive action verbs. Users may find having to click “OK” after reading about a critical error downright offensive, and it does not tell them what happens once they have clicked the button, either.

3. Only when I laugh (don’t try for funny)

A final word of advice: don’t try to be cute or funny.

I have seen several people insist, after my previous post about humor and error messages, that it’s fun and appropriate if the error isn’t very serious, such as a 404 not found message.

Instead of reiterating my first rant, let me tell you a story:

A few months ago, I visited a newly overhauled website that was boasting about its new backend and look and feel. I tried to use the site search, but clicking on links in my search results repeatedly took me to a “hilarious” new 404. Clearly, some pages had gone missing in their migration to a new platform. These things happen, of course, but “funny” not found pages pretty much assume that the user has clicked on a random rotten link or entered a wrong URL. In my case, I could not find the content that the site’s own search results promised. My frustration was mounting. Spare me the jokes!

Point of the story: it’s hard to predict all the scenarios and situations users will be in when they see our error messages. It is, in fact, about respect. You show it, or you lose it.

That’s what it’s all about

Creating helpful error messages can be very hard, but it’s so worth it. I would say it’s about the best use of a technical communicator’s time I can think of. Troubleshooting is where users tend to get the most frustrated, and better instructions in the product simplify troubleshooting. Less frustration, happier users. And happier users is what we should be all about.

(Photo by Gerry Balding on Flickr)

The post Helpful Error Messages For Fun And Profit appeared first on andedam.org.

Working with tech writing, I spend quite a bit of my time assisting in the writing and editing of text for user interfaces, as well as helping colleagues with other types of text. I bought this shirt for fun, but I think it has actually served a purpose as well. I am getting more “hey, grammar police, can you help me with this” requests from colleagues who are not writers, and I think the shirt has helped make it clear that I don’t mind this aspect of my job–in fact, I rather enjoy it. People realize they are welcome to ask for my help, and that if not, my help may still be … let’s say volunteered.

Bought and still available at One Horse Shy.

The post T-shirt Love: Grammar Police appeared first on andedam.org.

I first came across a link to the web app Hemingway on Twitter, and I was immediately smitten.

What Hemingway does

You can type or paste your text into the web interface, and Hemingway calls out:

• complex sentences
• adverbs
• uses of the passive voice
• fancy words and phrases that you can omit or replace with simpler synonyms

Hemingway uses an easy-to-grasp color legend to signal where the issues are. Accessibility-wise, this heavy reliance on color coding is of course bad news for colorblind users.

Putting Hemingway To The Test

I’ve run the tool on a few different texts, including:

• An IPCC fact sheet. Hemingway gave it a “10 Good” and minimal highlighting, which I think is an impressive result given the subject matter.
• The Wikipedia entry on Client-server architecture. Hemingway said “14 OK”, with some very complex sentences and a few uses of the passive voice.
• A random piece of Buffy fanfiction. “5 Good”, although containing a rather high number of adverbs.
• This blog post, which I kept re-testing until I was happy with the result. The first draft got “11 OK”, with a few complex sentences and some fancy words that were better replaced or omitted. You can see the result of the final run in the screenshot above.

I have tried with a few different texts and so far failed to get Hemingway to say anything but “OK” or “Good”. I even ran the analysis on a patent document where 74 out of 250 sentences were “very hard to read” and there were 86 uses of the passive voice. Hemingway still found this to be “14 OK”.

The Verdict

I dislike spell checkers and the grammar and syntax checking in word processors, and I have rarely bothered to use readability analyzers on my text. This might just be the tool that convinces me to embrace automated readability checking as a supplement to the editing and reviewing I otherwise may have access to. I gather that I like this tool because I feel like we’re on the same team. Clean, helpful, simple writing is what we want, and to that end, the tool has a clean, helpful, simple interface.

The app has some obvious shortcomings. The most obvious is that the analysis is not able to call out overall verbosity. A human (and hemingwayesque) editor would immediately strike down on long and repetitive text. I also find the individual highlighting a lot more useful than the readability score, which is often far too kind. If you manage to find a text that gets a terrible score, do let me know in the comments!

I will keep trying out this tool with my writing both for work and for this blog. The creators are trying to find out whether there is interest in a $5 desktop version that would be able to save and load files. I have signed up to receive notification when and if the desktop version releases.

The Hemingway app may not turn any of us into an author the level of its namesake. For self editing, however, it is probably the most helpful tool I have seen so far.

(The New Yorker has of course subjected Hemingway to the Hemingway app test.)

Update: I wrote some more about the Hemingway desktop app here: The Helpful Machine: 5 Self-Editing Tools to Improve Your Writing

The post Your own, personal Hemingway appeared first on andedam.org.