The Art of Technical Communication

Examples of mistakes in technical documentation are not hard to find - and I don’t think anyone, no matter how experienced, can ever be fully rid of them. I’m not talking about grammar or style, things that some writers get so carried away with, and which you can find readily enough in just about any technical manual. Nor am I referring to actual technical errors - it is always a dispute as to who is really responsible, the writer, or the SME. The mistakes that I have in mind are errors of information sequencing, in clearly communicating what is meant, or what you want the user to do. These mistakes are solely those of the technical writer - and to eliminate them requires sensitivity, training, and patience.

Consider the following step for Upgrading Wordpress:

Step 1: Replace WordPress files

..

2. Delete your old wp-includes and wp-admin directories.

3. Copy the new WordPress files to your server, overwriting old files in the root, except perhaps the wp-content folder (see “NOTE“below). You may use FTP or shell commands to do so. Note that this means *all* the files, including all the files in the root directory as well. If you use the default or classic theme and have customized it, then you can skip that theme.

NOTE The wp-content folder requires special handling, as do the plugins and themes folders. You should copy over the contents of these folders, not the entire folder. In some cases, copying the entire folder may overwrite all your customizations and added content.

Also take care to preserve the content of the wp-config.php file in the root directory. This file contains current settings for your existing installation, e.g. database sign-in information. Occasionally new versions of WordPress add statements to this file. (E.g. in version 2.5 the SECRET_KEY variable was added, see Extended upgrade instructions). Compare your existing file with the new installation file which is named wp-config-sample.php. Either transfer your settings to the sample-file and rename it to wp-config.php or copy the new statements from the sample file into your current file.

The underlined parts are what are problematic - and the line in red font makes it even worse. First, I’m to overwrite all files in the root directory (”except maybe the Content directory) - a few lines later I am told to make sure to overwrite ALL files in the root directory. Fine. BUT… , later, after I’ve done just that, there is this little addition “Also, take care to preserve the content of the wp-config.php file in the root directory”. Gee, thanks for telling me that AFTER you’ve told me to overwrite everything else! Lest you think I’m just nitpicking here - I discovered this documentation error after I myself fell victim to it and had to frantically locate the old wp-config file that I had luckily backed up on my computer long before.

Presenting information in a logical sequence is the backbone of giving technical instructions - in fact, of giving any instructions. Once you realize that users are not just going to read your instructions, but actually follow them, you need to pay close attention to the logic of your writing. The less familiar readers are with the material, the more slavishly will they follow the instructions - line by line, and to the letter. You cannot play games with users like these - unsure of themselves, they perform each line of the procedure, step by step - when they finally get to a step that cautions them to NOT do something that you instructed them to do a few lines back,  they will never forgive you - nor should they!

admin Errors