Your best bet is to hire me! I’m quick, cheap, reliable, and I take the time to learn about your product.

English - created by rude invaders!

However, if you don’t have budget for my copywriting and documentation services, then the following may help:

1. Don’t be polite

English isn’t a very polite language.

English results from waves of invaders – Celts, Romans, Saxons, Vikings, Normans – yelling orders to the locals  “GOLD NOW!“, and the locals answering simply so as to be understood,  ”Me give gold quick quick! Please not burn house!”

So, say “please” no more than once, and only when making a call to action, e.g. “Please get in touch if you want my help.”

Any more than that, and you’ll get the grammar wrong, or sound like a foreign waiter angling for a big gratuity.

(I’m sorry about this, but English speakers usually think foreigners are funny.)

2. Do use Imperative Mood to describe functions

In English, Imperative Mood - “Do this, do that” – isn’t just for giving commands. Nor does it sound harsh or rude.

It’s common in rhetoric – public speaking  - and in advertising, e.g. “Enjoy a fresh smelling house!” and “Stop worrying about virus protection!”

The advantages of Imperative Mood are:

• Short – Pack lots of information into very few words.
• Simple – Few words, less error.
• Call to Action – Imperative implies a call to action, which is a Good Thing.

3. Do use lists

Really, it’s OK just to list features and facts.

If possible, describe features using Imperative (see #2), e.g. “Enjoy peace of mind!“. If in doubt, use nouns with modifiers, e.g. “Full featured virus checker!”

Lists are great:

• Easy to get right – Few words to get wrong.
• Readers like them – Fewer words to read.
• Adds clarity  - Looks logical and organized.

The best lists use bullets.

However, for product descriptions, it’s OK to use periods, like this:

Easy to  get right. Readers like them. Adds clarity.

Don’t try to be elegant! If it’s a list, then present it as a list.

* * * * * *

 In short; keep it simple! Good luck. (And remember I’m here if you need me.) 

A new version of AnyRail is about to hit the tracks and somebody needed to check changes to the manual. I wrote the original manual, way back when it was DRail, and David was happy to come  back to me for the updates.

He said:

“Martin mag dan niet de goedkoopste zijn, maar zijn werk is wel in één keer goed en vlot klaar. Onze klanten zijn zeer tevreden over de handleiding die hij voor ons product heeft opgezet, en nu al jaren met elke update bijhoudt.”

Martin may not be the cheapest, but his work is first time right and delivered quickly. Our customers are very happy with the manual he originally edited for our product. He’s been keeping our manual up to date for years for every software update.

Macedonia… Netherlands… Germany… My map of satisfied clients is starting to look like the screen for one of the Total War games

As usual, I’m left a bit ashamed that my client’s grasp of English was far better than my grasp of any other non-English language! (Blame the 1980s Scottish education system, or blame my laziness.)

Even so, he needed that last 5% to make the site sound as if written by a native speaker – call it post translation localization. That’s what I’m good at, and that’s what I did.

He liked the result:

Martin did an excellent job for my website copy and to my surprise his services were affordable for my tight budget. He was also very responsive often replying in minutes. Highly recommended.

Мартин направи одлична работа со преводот и проверка на точноста на Англискиот јазик на мојата веб страна и на мое изненадување неговите услуги беа прифатливи за мојот скромен буџет. Топло го препорачувам секому кој има потреба од технички автор за Англиски јазик.

MS Outlook is missing a feature so blindingly obvious and necessary that it comes as a shock to find it’s not there:

Tasks with due dates don’t appear on the Calendar!

Really! Don’t believe me? Go check.

Yes, it’s true. As designed, the Calendar and the Tasks are two distinct subsystems… like room-mates locked into a permanent sulk… or the AD&D Brawl and Combat systems.

It’s frankly bizarre that a behemoth like Microsoft could put out a product with such an obvious omission. So, if the Outlook designer does have those nightmares, it’s probably because he or she is sufficiently forgetful to have genuinely gone to work sans-jeans!

"Call client" is actually a task...

Fortunately, there’s an independent software provider willing and able to hand you a pair of chinos to cover the shame of your particular Outlook installation…

TaskToCal syncs the MS Outlook calendar with the task list. Tinker in one place and the changes appear in the other.

Oddly, this little masterpiece didn’t require much documentation. However, I was glad to get the gig, especially because I got to make some suggestions about streamlining the UI text. I delivered my work as a Help and Manual project, and the client was very happy:

“Do you love writing software but you hate writing documentation? Then don’t burden yourself any longer. Ask Martin to do this job. The result is pragmatic and overwhelming at the same time. He does his work on time and delivers more than you expect.”

Drop me an email to see how I can help you with your documentation…

I can read it one-armed while cuddling a dozing child. I can catch up on classic out-of-print Science Fiction, without cramming the house with dusty books or spending a fortune.

I can even legally download the complete works of Edgar Rice Burroughs free from Project Gutenberg without spending a fortune on collectible paperbacks with rather too raunchy covers.

So, no, I’m not one of those people who laments the loss of the feel of the book, the smell of the paper. Give me content. Now!

Alas, when I say  I  love my Kindle, I really mean I love my ebooks.

Good reviews on cnet aside, the Kindle is very unlovable indeed.

Sure, we’re all used to the “Mac-rosoft” logic of menus and clickable links. We don’t need an Interface Metaphor anymore.

However, when a device is a replacement for Something Real, you’d think the designers would have thought through some use cases for the original.

I doubt the Amazon  designers did this. To be honest, I seriously doubt they  read books for pleasure.

How the Kindle matches up against use cases for a paperback book

Think about it. The two main use cases for a paperback  have to be:

• Linear reading: I read one page, then I read the next. Sometimes I  back-up a page to check I read it right. Mostly, I just trundle through the text.
• Flicking: Some books have maps, glossaries, dramatis personae and end notes. Others place their illustrations in one clump. I need to flick to them and then back to  the text.

Linear reading – yes, well done, the Amazon designers managed to remember a forward and back button. (Woot!)

Flicking…? With the exception of the way it handles end notes, the Kindle is a flicking fail.

Why the Kindle is a flicking fail

Flicking is all about  back-and- forward action - glance at Glossary, then back to the description of the battle.

How does this go with a Kindle?

I’m reading Six Months Without Sundays. What on earth is TRiM? OK. Let’s check the Glossary…

1. Click the Menu Button…
   The menu opens.
   (I have lots of options, including tinkering with the  WiFi. However, I think I want Go to.. , which is handily highlighted.)
2. Select Go To and hit the OK button.
   A panel appears offering me 6 standard destinations.
   (Hmm. “Table of Contents”, “Beginning”, “Page”, “Cover”, “End”, “Location”… But I want the Glossary. Is it in Locations… Oh, that just returns me to my place for no apparent reason! OK, I give in…)
3.  Select Table of Contents.
   The ebook’s Table of Contents opens.
   (Finally! Now I just have to arrow down to the glossary.)
4. Select Glossary and hit the OK button.
   A panel opens.
   (Do I want to “cancel”, “create note”, “full definition”, or “follow link”…?)
5. Find the required information.
   (Oh, “TRiM” means “Trauma Risk Management”. Cool.)
6. To return to your place, hit the Back button several times.
   (Great. Oh, hang on, what’s a “Gimpy”…?)

It takes four (4!) menu steps and many more clicks to get to the glossary. Once you’re back in the text, you have to do it all over again.

This is  rubbish! What were they thinking?

Yes, I could bookmark it, but: using a bookmark requires two navigation steps, and even more clicks; and consulting a glossary is a very routine expectation – I should not have to set it up myself.

Ways Kindle could be better for flicking

Assume we can’t add extra buttons, or get the Kindle to treat the Glossary like a dictionary and have the   definitions appear tool tips… what could we do to make it better at flicking?

Let’s mess with the buttons. Here they are:

Table of Contents button replaces Menu button

Going to the table of contents is a routine action! It shouldn’t be a roller-coaster adventure through a menu tree.

So let’s turn the  Menu button to a Table of Contents button. The table of contents screen can have an item on that leading to the other options.

Forward and Back arrows skip bookmarks, not chapters

At the moment the Forward and Back arrows work like the skip buttons on an MP3 player.  However, instead of skipping tracks, they skip chapters.

How often do readers navigate by chapters? Remember, the Kindle remembers your place; you don’t need to pick it up and go, “Hmmm. I was halfway through chapter seven…”

The arrows would be better used to skip between bookmarks.

It’s not rocket science!

Looking back up at my review, I am starting to wonder whether the Amazon designers thought they were designing an MP3 player, or that they wanted to make the Kindle like one. Or perhaps they saw the shape of the data – the chapter structure – and organized their UI around that. One way or another they missed an opportunity to produce something that really enhanced the reading experience.

It’s a pity because it’s not rocket science. They just needed to sit down with people who actually read books and look at how they use them.

(If you want some help in revising your UI, drop me an email.)

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!