The Lost Art of Documentation

When I first worked with computers in the 1970s, they were not meant to be user-friendly. You had to go to class, or read a long and detailed manual, before you could expect to be able to step up to one and do something useful. And you had to interact with the machine through a keyboard and text display. I accepted it as a fact of life; I got good at it.

In the 1980s and 1990s, graphical user interfaces came into use. For some things, it’s useful. It would be really, really difficult to draw on CADD without a graphical interface. (And when I first used CADD, in the 1980s, it was still an old-school system in that one had to go to class and read the manual before using it.)

But graphical interfaces made it possible for other programs to have a more user-friendly, point-and-click interface. You didn’t need to read the manual anymore.

Just mouse around: you’ll figure it out.

Well, maybe.

I remember one frustrating even├Čng in the 1990s with a graphical spreadsheet program. I wanted to change a column width and couldn’t find the command for it. It took ten minutes of cursing and swearing before I realized that I had to grab the end of the column header with the mouse and pull it to the desired width.

So instead of interacting with the machine like an adult, I have to point at what I want, like a three-year-old.

I learned that trick, and many others, and I’ve made my peace with graphical interfaces.

Meanwhile, the manual that used to be required reading before doing something useful has atrophied and disappeared. The last software that I bought that had a proper manual was QuickBooks, back in 2005. It included not only a description of how to use the program, but a discussion of some of the basic and necessary principles of bookkeeping. It was the last and finest of the dinosaurs.

I had made my peace with this method of working, until this week.

I rent a computer server in a data center somewhere for my business. Last Sunday, it failed. Not a major problem: I had some measure of warning, and I keep backups, so no data lost. The good people at the data center changed out the server and set up a new one.

Most of the reconfiguration went smoothly, until it came time to install the SSL certificate for encrypted Web transactions. One of my clients insists that their data be secured in transit, even though it’s not financial and nor particularly confidential. On the first server, I had used the data center to acquire the certificate, and it went smoothly. I had the files from the original installation, which I needed to reinstall.

OK: mouse around, without a manual, find where the SSL certificate goes, paste it in, then go to ‘Domains and Websites’ to turn it on.

OK, now I’m in Domains and Websites: how do I turn it on?

The data center has tutorials for doing things, and I found the little tick box and selector to turn on the certificate. OK, now we’re good.

Well, almost. I tested the connection with several browsers. It worked with all of them except for Internet Explorer, which somehow got the wrong certificate and said that the site was possibly fraudulent.

I then spent a day and a half trying to fix this: looking around through the user interface, examining files on the server directly, testing. I thought of swapping the certificates inside the server, but couldn’t determine if there were other consequences (like not being able to access the server again). Still not working.

Could I have asked the people at the data center for help? That didn’t work when I tried it before: I couldn’t get e-mail working when I first got the server, wrote in for help, and they couldn’t figure out why it wasn’t working. I found that to start e-mail, I had to issue the command to turn it on, and then restart the server.

Finally, last night, I Googled the problem with a different turn of phrase, and found the answer. I should properly have installed the certificate in a different spot, and enabled it through the IP address, rather than the domain name. With that information, I fixed the problem in three minutes.

Just mouse around. You’ll figure it out….

But when?

One thought on “The Lost Art of Documentation”

  1. When I mentioned, in another comment, that I had problems with Yahoo! Mail I forgot to say that I had Goggled the problem and found others had the same experience. There is no doubt in my mind that the problems are at the Yahoo! end. Also, from my own experience, manuals are only as good as the people who write them. A lot of software is released with bugs. We all have to ‘eat the dog food’ even though we should not have to. Sad, but all too true.

Leave a Reply