Working my way through 200+ pages of this…

A very small sample of some documentation I’m editing at the moment. Actually, I’m doing much more than editing it — I’m rewriting it. When you see the example below, you’ll probably understand why…

This is what the developers in another country wrote in the original admin guide:

DELETE LOOKUP VALUE: This button when clicked will update the selected string value, here we need to first select the value as the particular value will appear in the “New Lookup Value” text field and then required changes are made into the text field followed by a click on the “UPDATE LOOKUP VALUE” button and then hit on “Submit” button to permanently save the changes.

And this is how it now reads after I deciphered it (yes, they got it wrong too — they’d copied in what they wrote about the Update button into the information on the Delete button), tested it in the application, and rewrote it:

1. …
2. …
3. Select the lookup value you want to delete—it gets loaded into the New Lookup Value field.
4. Click Delete Lookup Value.
5. Click Submit.

I’ve only got another 100 pages of this to go….

Oh, and in addition to making it more readable, the text has gone from 65 words (372 characters) to 23 words (129 characters), an almost two-thirds reduction.

If this manual was to be translated, the savings in translation costs over those 200+ pages would be worth far more than what it cost my client to pay me to edit it.

Paying someone to edit your work pays off handsomely if you’re considering translation into another language, and these cost savings increase massively the more languages you have to translate to. A side benefit of editing is that you end up with readable and comprehensible text–you won’t annoy and anger your customers with turgid prose that they have to read several times over to figure out what it’s saying. If you re-read that original piece of writing, you can well understand why some people refuse to read manuals.

See also (from Sharon Burton):

• What customers are saying about product documentation — and why they are mad: http://www.sharonburton.com/consumer-feelings-about-product-documentation-results-are-in/
• Webinar recording on why customers get mad: http://www.sharonburton.com/recording-of-why-your-customers-are-mad-at-you/

[Links last checked December 2012]