In my house there's this light switch that doesn't do anything. Every
so often I would flick it on and off just to check. Yesterday, I got a
call from a woman in Madagascar. She said, "Cut it out."
- Steven Wright -
Trouble with Documentation These Days
I spent an hour or so today helping my Dad work on one of his websites. His sites are set up as WordPress blog sites, like this one that you1 are reading. WordPress is OK. No doubt it has its detractors. But it works well enough for my purposes, and for Dad’s.
However, I have never been a fan of editors that run as web apps, such as are directly available in WordPress. Oh yeah, I know, I know, Google Docs and the Cloud, and The Desktop is Dead! and blah blah whatever. But I checked a couple of these editors again recently, and concluded that any of them would prove totally disastrously unfriendly for Dad. He recently switched from his ancient Windows machine to a new Mac Mini. He chugs along quite well in MS Word on his Mac, but I thought he should use something besides Word to create content for his websites. (Anyway, Word for Mac does not include blog publishing AFAIK, although the Windows version does.)
So, after a few minutes of googling, I discovered Blogo. It is blog publishing software that runs natively on the Mac. Once downloaded from the Apple App Store and installed you get a free 21 day free trial. After that it cost $CA35 or so. When I fired it up it appeared to be polished and pretty simple, so I turned Dad loose on it.
After Dad had edited for an hour or so using Blogo, he had some question or other that he wanted me to answer about it. Now, once set up to handle a WordPress site, Blogo apparently downloads existing posts so you can tinker with them locally. This is convenient. When I sat down to look at what Dad had being doing in Blogo, I saw that posts are organized as a list in the app (the Post List) by title of post. When you click on the title of a post in the list, the content of that post appears in the edit area to the right of the Post List. Each title has a little icon beside it. One of the titles was repeated three times, and each of these had a different icon beside the title. When I selected a post by clicking on the title, each of the three with the same title had slightly different content. And another of the posts listed in the Post List behaved differently. Even though the post was clearly on the website, and therefore (I assume) should have been downloaded to Blogo for local editing, clicking on its title in the Post List did not bring up its content in the edit area. In fact, selecting any another post (whose content did appear in the edit area) and then selecting this odd phantom post by clicking its title left the content of the previous post in the edit area. So, while it appeared that I had selected the “phantom” post, I apparently hadn’t. Nothing I did seemed to allow me to bring up the content of the phantom post.
Which brought my attention to the little icons beside each title. “Those icons means something”, I thought. “They are trying to tell me something about the state of each of the posts.” There was a little paperclip icon, a page with a folded corner (denoting a bookmark?), and some other ones that oh I don’t know probably mean “King Tut Buried Here” or some fucking thing.
Here’s a picture:
Right. Being extremely old and unhip and thus necessarily baffled by technology, I did something that just isn’t done by the cool kids these days, or so I am told. I clicked on the Help button and looked at the Blogo manual.
Now the manual is slick, really quite good looking. Probably someone with training, or at any rate with some natural ability in graphic arts did the thing. And guess what.
IT HAS ALMOST NO INFORMATION IN IT.
The manual is like a marketing thing. There is no mention of those little icons. None.
Thus, I cannot figure out why some titles appear multiple times in the Post List. And I cannot figure out why the content of one of the posts does not appear. And I cannot figure out what the fuck those little icons mean. This despite lots of clicking and double clicking and whatnot.
So Here’s The Problem
It seems that people who produce software don’t do user documentation any more. Or, most of them don’t.
Back when I was a programmer lad, before I stopped doing that and became a (not very talented) lawyer for a while, software documentation often came in two pieces. There was a User Manual and a Reference Guide, or the equivalent. The Reference Guide was intended to be a complete reference. Everything was in there, unless by unintentional oversight. The User Guide was friendlier (sort of) and had examples in it.
When I left the legal profession and came back to software development, I discovered that small applications that one might purchase for use on a desktop machine no longer followed this paradigm. The User Manual and Reference Guide were not infrequently replaced by a single volume that had nothing but examples in it:
Perhaps you would like to create a new blurg and then frob it so that it meets the your extremely demanding BUSINESS needs in this high-speed competitive world which we have written wonderful software to do. So HERE’S HOW!
Well, perhaps I would. But perhaps I would instead like to do something that is not among your cute little examples. But I guess I’m not going to find out how, am I? Unless I go on a mailing list or user forum or something. But look it up in the documentation? What the hell is that, some kind of old person thing?
A year or so ago I ran into this with iTunes. Every song had a little check box beside it. So what is the checkbox for? I could find no mention of it in the iTunes “manual”. I actually posted a question on the Apple support forum asking, not “what are those check boxes for?” but “where are those check boxes documented in the iTunes manual?”
But this question just did not compute for people on the forum. I got lots of replies telling me what the check boxes are for. But apparently this is a kind of folk knowledge obtained by, you know, just clicking on the check boxes and seeing what happens.
My Android phone is the same. It has a bunch of tiny, tiny icons at the top that blink and whiz and whir. But my telecom company and the Android people (whoever they are) seem to want me to treat using my phone as a kind of experimental science project.
Naturally, I am aware that this is a generational thing. When I asked my niece about her iPhone, she said that she just uses it. “What about that thing there?” I asked, pointing to an icon on the iPhone screen. “I don’t click that”, she replied.
So that’s what the epigraph at the top of this post is about. Just click and poke away and see what happens. Maybe it will be something good and maybe it won’t. And if you are under 40 years old it will possibly never occur to you that there might ever have been a different way to find out what that thing does.
I realize that “you” only exist in my hopeful imagination, because it is highly unlikely that anyone will read this blog.