I don’t mean the sort of fancy theoretical considerations they teach you in HCI courses. I mean just the basics:

• Make the interface reflect its real world domain.
• Keep navigation simple and consistent.

Late last year, I was lucky enough to work on documentation for a system that’s a good example of how to “do it right”.

FastMaint essentially turns your PC into the equivalent of a fully-staffed maintenance office. Not only does it handle work orders and the resulting workflow, among other things, it also tracks inventory, rostering, locations and equipment. It even warns you if you’re trying to do something impossible or unwise…

With so many different entities to manage, this could have been a horribly complex piece of software. However, the SMGlobal team managed to make the product so intuitive that even a deskbound techwriter such as myself quickly made sense of it.

They achieved this by putting in the hard work required to keep the interface consistent and convenient. Here’s an example:

• If you’re a maintenance professional, then all this should make sense to you, even if this is the first time you’ve seen FastMaint!
• If you’re looking at an entity or list of entities – here, equipment located in a building – then there’s a button to create or add a new one.

In short, you – the user – can concentrate on the task in hand, without wasting brain space on the software.

All this may not be rocket science, but it requires the sort of thoroughness you associate with building an actual rocket:

• Somebody must have gone to the trouble of learning the terminology used in maintenance departments, then made sure that the screens reflected it. (This probably meant acting as a sharp-eyed gatekeeper whenever developers became “creative”.)
• Somebody else had to slog through the UI, putting in all those buttons, creating all those editors…

When they graduate from college, most young coders dream of wrestling with algorithms and architectures, not putting in the kind of meticulous effort on display here. However, if this were a launch vehicle, then I’d cheerfully ride it to the stars.

If you don’t believe me, download the application and take a look for yourself.

If you do that, you’ll also see my streamlined documentation that builds on the application’s ease-of-use.

It’s usually harder to cut, rather than expand, text, and there’s always the fear of leaving out Something Important.

However, my contact at SMGlobal, Sanjay Murthi, pronounced himself “…happy that you have been able to reorganize and simplify the help documentation.”

So, I like to think I’ve turned out an online help worthy of the product.

Just wanted to forward this little bit of praise to you from one of our customers:

 ”I was reluctant to invest in any planning software.  I recently stumbled onto your website and started playing with the free download.  I was hooked immediately.  Also, AnyRail has done a very good job with the manual – it’s clear and to the point.  You guys think like humans instead of software designers.  Great job. ”

Thanks again for your great work last January.

Mostly, customers only send you an email when something’s wrong! So, it’s nice to think that this customer felt moved to put finger to keyboard because something was very right….

It’s certainly an indication that good documentation helps to sell products, especially when the potential customers expect to download free trial versions. If they can’t get the thing working within a few minutes, the chances are they’ll hit Uninstall and “Move on down the line” (to your rival’s product).

"I'll always be a sucker for start-ups with quirky products, and for companies based in interesting locations..."

I’ll keep on fixing prices upfront, so there’ll be no nasty surprises. As before, there’ll be discounts for small projects I can fit in between the big ones. And, I’ll  always be a sucker for start-ups with quirky products, and for companies based in interesting locations…

This year I’ve done a lot of work on user-interfaces, ranging from simple post-translation localisation, through to full reports on structure and usability (I like to think of this as “pre-emptive techwriting”). I’m going to add this to my list of core services – just as soon as I can work out a consistent pricing system!

I’ve also put in a good few hours working on website text. Sometimes clients just needed me to check the English. Other times, I’ve created the website copy more or less from scratch. It’s similar to my regular documentation work, but requires more thought and hence more time. That’s another service to add to the list once I’ve had time to think about pricing.

What hasn’t changed is that I’m still fast, still friendly and still having fun. So, roll on 2010!

In explaining my work to a translator, Gert (my main contact) neatly summed up what I do…

So the original text was…

blah-dee-blah-dee-blah-blah-dee-blah-dee-blah-blah-dee-blah-dee-blah-bl a-dee-blah-dee-blah-blah-dee-blah-dee-blah-blah-dee-blah-dee-blah-blah- dee-blah-dee-blah-blah-dee-blah-dee-blah-blah-dee-blah-dee-blah-blah-di e-blah-dee-blah-blah-dee-blah-dee-blah-blah-dee-blah-dee-blah-blah-dee- blah-dee-blah-blah-dee-blah-dee-blah-blah-dee-blah-dee-blah-

After DD’s changes it is…

To do blah-dee-blahh:

1. Blah-dee-blah blah blah

2. Blah blah blah

(With several spelling errors corrected.)

He was of course, correct.

I’ll cheerfully admit that I don’t do anything special, but what I do do, I do very quickly indeed, and from the user’s point-of-view. This makes it more cost effective to use me, than to lock some poor coder in a room with a Help Authoring Tool – and I’ve yet to see a HAT that’s both user-friendly and powerful – and a copy of Technical Writing for Dummies.

EDIT: When I told Gert about  this blog post, he said I could quote him on the following:

Working with Documentation Doctor is a pleasure, he works quickly and for a reasonable fee. If you have any doubts or questions, feel free to contact me: gert at watchftp.com

Shepherds slip an extra sheep onto the common land until it’s a desert, people leave their rubbish at picnic sites until nobody wants to eat there, drivers take shortcuts until the side-roads are clogged, sunbathers turn up their stereos until nobody can hear anything… and nowadays, “trolls” and “spammers” choke up Internet forums with the intellectual equivalent of white noise, or worse.

DeepTrawl is intended to stop this happening to your patch of the web.

It’s like having a killer robot to cull illicit sheep, sweep up the rubbish, keep people on the highway, and jam noisy stereos, that also checks the footpaths and updates the signs, and even returns lost wallets… OK, I’ve probably pushed the analogy a bit far.

In a nutshell, DeepTrawl sweeps for inappropriate forum postings, including credit card numbers, and checks your site for spelling, valid links, and optimal design. It even suggests possible improvements.

So, maybe a killer robot with a friendly geek inside.

You’ll understand, then, if I approached redrafting DeepTrawl’s documentation with a certain trepidation. However, despite being a powerful bit of kit, DeepTrawl is easy-to-use, with most of the important features no more than a click away.  The only real challenges were its very technical  capabilities, but a few iterations via email nailed these.

Jonathan Matthews of DeepTrawl seemed satisfied with resulting HTML help pages:

Thanks for the great work! This really helps the usability and  professionalism of DeepTrawl and I found the process very easy. If you ever want a recommendation just shout!

A few years ago, we’d have had to make a special trip to the library or thumb through military bookseller catalogues for something on 1940s British tanks.

Maybe next year, all I’ll have to do is point my mobile at the barcode.

There, in my hand, will be archive footage… original blue prints… historical details… links to Museums… an invitation to enter a competition by uploading a photo of the finished  model… and links to other model kits and related books.

A few clicks and I’ll be happier, and perhaps a little poorer – can’t… resist… those… tank… books – and I won’t have even got up from the workbench.

It’s called Mobile Marketing, and it’s turning the world into a point-and-click environment.

The snag with Mobile Marketing is that it mixes the Internet with mobile devices and the real world. You have to be able to field and send text messages, put up special mobile-friendly websites (WAP pages), generate barcodes… all technical stuff, some of it quite complex.

Historically – in this context, that means perhaps “the day before yesterday” – the complexity was expensive. You had to be a big player or a gambler, because no excursion into new marketing channels is guaranteed to succeed.

Then, along came Moozey. They’ve automated the thing. You can sign up, design a campaign, activate it and analyse the results, all online. You don’t need to speak to a salesman or any other sort of rep.

They’ve not so much “cut out the middle man” as done away with consultants as well, reducing the whole thing to just another application, albeit one you use on the web. Better yet, they’ve hacked down the cost down to the point where you can afford to test the waters.

Products that hide their power behind a simple interface are always impressive, so I was very pleased to be asked to help optimize Moozey’s documentation, check the interface for consistency, and give the homepage a polish.

Working on software that’s undergoing development is never a “surgical strike”; you have to engage with the product and its purpose, and build up real working relationships with people you’ve never met, while at the same time not getting underfoot. I think Can, my contact at Moozey, feels the same: 

As a fresh startup developing Moozey, we were constantly in rush; trying to catch up with our countless project deadlines. We are glad that we have found a “co-worker” like Documentation Doctor. Most of the time he was even faster than us, completing his job always in a timely manner and in perfect quality. He is now virtually a part of our team and we hope he will continue to work on Moozey and our other future projects.

In truth, I had such fun messing about with the Moozey user account, I even considered replacing my old mobile with something that can actually read barcodes and display WAP pages…

Of course, I do use PowerPoint. It’s one of those business tools you can’t avoid, not so much “Best of Breed”, rather “Least Bad of the Bad Bunch”. What I don’t get is people who use the thing for fun!

The worst crime of all is afflicting your friends with a PowerPoint presentation of your holiday snaps, with all those “special effects” that remind one of unemployed double-glazing salesmen in nylon trousers trying to learn how to sell used cars. A few minutes of that, and most sane people will be reaching for the nearest blunt object.

Slide Effect is designed to save you from being bludgeoned to death with your own holiday souvenirs. Instead of grudgingly slumming it as a slide machine, Slide Effect lets you turn your pictures into a high-energy audiovisual extravaganza, with synchronized music and cinematic special effects.

Though it won’t – unfortunately – kill PowerPoint, Slide Effect does come from that mountainous land formerly known for its professional soldiers. For this reason, Alain Bocherens, brought me in to localise his website and tune up the presentation of the application’s easy-to-use features.

Once he’d applied the changes, and well after he’d paid me, I checked over the website for typos, and things that didn’t actually work in context. I’ll admit I was partly motivated by fear of being skewered to death by Swiss pikemen, but it was worth it. Alain said:

If I need another documentation/proof reading task I won’t hesitate to work with you again.

Imagine my surprise, then, to discover that many Armenians are nowadays happiest doing battle with complex programming challenges, in this case resulting in RIATest, a powerful tool for automatically testing Adobe Flex applications.

When I see products like this coming from formerly “obscure” corners of the world, I start to wonder how long it will be before we Brits start to feel like the naked guys daubed in woad again! The thing is, thanks to the Internet, physical distance is no longer a protection.

When I localised a press release and revised the documentation for RIATest, Tigran said:

You delivered good work which was essential for our website and documentation. The project went smoothly and I would not hesitate to recommend your services to others…

So, I can rest easy knowing that I’ve established cordial relations with our possible future overlords.

Right now, however, I’ve got a brief window in which to write up a few of the projects that have kept me glued to the keyboard…

To an extent, if the software does what the user wants, then a UI only has to be “good enough.”

However, there are one or two seemingly trivial UI oversights which – I think – can create a kind of mental friction… eating away at your user’s sense of certainty and security, leading them to make errors, or suspect errors.

Let me propose, as a rule of the thumb, that if it’s hard to document, then it’s probably also harder than necessary for a user to understand.

So, things which bug me  – your humble techwriter-for-hire - probably also bug your u$er. (And – if you’re not my client, please remember that I might well be your user… or would be, if your interface didn’t put me off .)

Here are six ways to avoid the most common UI issues. None of them are rocket science!

1. Name everything, including any groups of fields and lists. This makes it easier to describe the interface, and avoids sentences such as “Select a format (lower right group of fields), then, in the green list, select a file”.  It also makes the interface less intimidating for the new user.
2. Use names consistently throughout. If you call a spade a “spade”, don’t then call it an “implement”, and then a “digging tool”. A User Interface is not the place for elegant repetition, because it’s very easy to confuse synonyms with parent categories.
   In other words, the user may wonder whether perhaps the entity SPADE is a subset of “DIGGING TOOL”, itself a subset of “IMPLEMENT”. (And God-forbid you do then decide to add more entities, and forget to rationalise your terminology.) Get a lexicon dude, and stick to it!
3. Avoid …. like … -  You know what I mean? Those “friendly” fill-in-the-blanks sentence/field combos. They do look friendly, but what entities and parameters is the user dealing with? There’s nothing to hang the information on.
   Also, these are potentially (your) murder for non-native speakers. Which is easier to translate, a complex sentence, or a table of fields and noun field labels? How would the resulting support call go?
4. If it’s not a wizard, don’t pretend it is one! Repeat after me, “Wizards don’t need documenting. Wizards are linear.“ 
   If you have a complex set of options, don’t present them in a one-way fashion; users often want to go back to confirm their choices before pressing OK!
   Also, imagine a support call where you want to check their settings… 
5. If it looks a bit like a standard office application, make it work like one! I know you think you’ve written a clever time-management system, but to the user it’s either a calendar or a special spreadsheet, and they’ll expect it to be organised as such.
6. Don’t reinvent the wheel! Be honest – is your feature so very unique that no interface element created in the last ten years could handle it?