Your docs are wrong. Maybe.

Last week, over on a blog called Flyosity, there was a post: Your design is wrong

I liked it, I liked it a lot. Although many of the errors it cites may seem like rather small things, I absolutely buy the idea of objective design mistakes. It got me thinking about examples from the world of technical communication and information design.

Then, a couple of days ago, the perennially awesome A List Apart ran the article Good help is hard to find

Completely reasonably, it’s pretty down on bad help, particularly help that’s long-winded or tonally alienating. I chewed a pencil for a bit and came up with some more tech comms “errors”.

To what I’m sure will be your enormous surprise, most of the ones I came up with boil down to my recurrent hobby-horse:

It’s not that nobody reads the help, it’s that nobody wants to spend time reading the help.

Anyway, here’s 5 ways I think help can be flat out wrong:

Describing the user interface

You can’t document your way out of a bad UI, and you don’t need to describe the minutiae of a good one. Or a familiar mediocre once, come to that.

If you’ve ever found yourself writing something like:

Select Open… on the File menu to open a file

You’ve done it wrong. You’ve also wasted your time, bloated your docs (see: tl:dr), and – in that specific example – broken the rule about writing in the right order that we’ll get to in a minute.

Ideally, the only time you spend writing about the details of the user interface is the time you spend making sure that the buttons and menu items and so on all have the right names in the first place. It’s massively more useful to explain how to do specific things with a product than it is to explain what the bits of a product do. The former comes closer to actual user problems, the latter makes them think about how to solve their problems – something they really don’t want to do.

Writing in the wrong order

In Matt Groening’s Futurama, a caricature bureaucrat asks “Why isn’t this jacket in alphabetical order? The zipper should be at the bottom.”

If you don’t find that funny, I feel sorry for you. If you’re a technical author, and you do find that funny, and then a small part of you realises that actually, you’d want the zipper at the bottom in order to put the jacket on, I salute you.

What? I’m getting there. Let’s re-write that previous example:

Select Open… on the File menu to open a file


To open a file, on the File menu, click Open

The instructions are in the order you’d use the UI, and the boldface-emphasised UI elements that stand out now end on the final one you want. The purpose of the exercise is at the beginning, so you don’t have to parse the whole sentence to resolve the sense. This enables F-Pattern scanning and rapid clause-level discard of irrelevant information; both crucial web reading behaviours.

The zipper is at the bottom, and all is well.

Hiding behind a flash portal

I’ve ranted about this. I won’t bore you twice. Don’t do it, it’s unhelpful and there’s no excuse.


… is an acronym of “too long, didn’t read”. You know that, right. You’ve been to earth.

This has its origins in blog comments and the like. It speaks not of some tired patrician jeremiad on the attention spans of the young, but rather of the fact that humans generally won’t spend a lot of attention if there’s a low perception of likely return.

The List Apart article makes the brevity point, but I’m restating it because it’s really, really important.

There’s an article on Tefl Spin, too, claiming no list should go over 7 items for more or less this reason. The 7 there is very likely prompted by the questionable assertion that we can think about 7 things at once. Cognitive load is well worth remembering. Quite apart from looking like a poor attentional investment, long-form complex information will very likely lose people.

If any meaningful, coherent sub-unit of your help is really long, it’s probably at least partly wrong. This could be as simple to fix as a run-on sentence or a two page list. It could also be more complex, like a single topic that’s just trying to do too much at once. Regardless, we have a duty to get people back to the task they were trying to do as quickly an easily as we can.

Topics don’t just need to be brief. Their first impression needs to be of something you can quickly get your head around.

In the spirit of fairness, here’s one of ours . Yeah, it sucks, and we’re working on it. In fact, I think my colleague Tom is replacing it with a short animation.


The List Apart article is cautiously welcoming of the FAQ style, noting that they’re open to being done badly. That’s probably fair.

A problem we’ve had here, and one I very much doubt to be unique, is that FAQ pages have been written by people working on a product launch who are neither information delivery specialists nor particularly technically well-informed. They’ve often seemed to duplicate help content, but with less rigor and accuracy, and they’ve been created because that’s what we do.

That last one is a red rag to a content strategist.

Ideally, FAQs will always fail the content strategy “What is it for?” test. They’ll fail because the information they would contain is delivered more accessibly and to a higher standard everywhere else. You product page will tell you what the product is, and what its requirements are; your help will tell you how to do things with it, and so on.

FAQs, hiding as they do behind facade of harmless familiarity, ought to be utterly redundant. They’re a bucket for unsorted information, a data scrapyard heaped in the way of actual, useful content.

Oh, and their usability is completely predicated on the phrasing of the question; a problem amplified by the question construction making them wordier and less web-scannable. I just can’t see FAQs being the best way to help or inform people.

Any suggestions?

How about you guys? What little (or not so little) things are just plain wrong? Am I wrong about things being wrong? Salted popcorn – yes or no?