guff

Documenting the documenters

You may not know this, but I’ve been spending a bit of my not-so-valuable yet still not-unlimited spare time working on the *new* online documentation for WordPress. There are a number of us crawling over the various materials, chipping in where and with what we can.

You can see the initial fruits of those labors here.

The underlying documenting tool in use is a wiki. If you don’t know what that is, go read. I’ll wait……Now, you may see a method like this is at best prone to errors, haphazard coverage of topics, and vandalism. And I’d have no choice but to agree with your observation. How very astute of you! In reply I’d point out that though circumstances often require an on-hand staff of technical writers to detail the ins and outs of a system or tool for end users, the very nature of the beast for open-source products, of which WordPress is one, means circumstances leave you with different options. And rarely do these include the funds and/or resources needed to bring in the professionals.*

For WordPress, developers would need to take the time to put the documentation together, or rely on a group of (assumedly) knowledgeable users to do so. Both require dedicated effort and additional supervision of a sort.

In the case of developers doing all the documenting, development on an open source project usually means programming in your spare time, and to lay another (and time-consuming) project on their shoulders is far from the best solution. In one way or another, such a task must cut into the time they have for programming, working on the software; and complicating matters, it may require they intermingle the two during the development cycle, because who is honestly willing to wait on the documentation once the programming side of a project is finished? Often the developers, understandably, don’t want to do it: akin to support, documentation is like an unappreciated stepchild in the fairy tale of software, except there’s no Prince Charming awaiting them at the end. And risking a chance at hurt feelings, the developer with the skill to write clearly and expositively to an end-user readership represents a huge deviation from the norm. As I’ve been required to edit—or as I came to see it, translate—developer notes for public consumption, I have a great deal of anecdotal experience to back this up.

The other option, which is to entice erudite volunteers from the user base, has problems but is certainly the better method. For one, it allows a documentation team to work in tandem with developers as work on a project progresses, so there’s a good likelihood both will come to completion at the same time (when that’s a requirement). However, it demands Big Ole’ Horkin lines of communication from both teams. Mainly from the programmers, as documentation, even when the real writing chores don’t happen there, originates from the developer’s desk. Keeping those communication lines open and flowing in the right direction is of major import, and a huge demand when supervising a project. And when you find that egos (in a technical environment, there will be a number of large ones) when bruised (and they will get bruised) lead to lockups in the process, you may also find them insurmountable without the control leveraged in workgroups within a normal business, i.e. salaried, environment. People problems are inherit in activities requiring people as a primary resource, but far more so where the supervision and organizational framework are nebulous at best, which is fairly typical in open source.

So aiming a select group of users at the documentation can be difficult to manage, but is doable. At least, more so than having the developers perform double duty. Then what need is there for something like a wiki, which allows just about anyone to participate willy-nilly in the documentation process? That’s a good question. And when you come up with an answer, be sure to let me know. Until then, let me pass along a personal if far too lengthy anecdote. A parable, if you will. Or consider it a partial clue:

Once upon a time, I bought my first *professional* word processing application—WordPerfect for Windows, version 5.2, up to then the most expensive piece of software I had ever purchased. Amazing how my most recent “WP” acquisition cost me nothing…

WordPerfect offered many powerful, and several amazing, features (at least to this boy, having just stepped up from barely adequate DOS apps), but one of the main uses I planned to put it to was editing a regular stream of simple and un-publishable short stories. Fiction manuscripts in general require specific formatting elements, all quite standard and one would expect easily handled by a workhorse like WordPerfect. One of these is a left-indent on the first line of each new starting paragraph. This had been a bane to me on typewriters, as I was forever forgetting to hit the Tab key before typing onward. Word processing on a computer solved that, thankfully, by automatically sticking a Tab in for me. I could stop worrying about the damnable indent and worry instead over the next paragraph making sense.

Except, it seemed, when I got WordPerfect. Out of the box it lacked a major function I wanted from it: automatic first-line indenting. Considering a 5-year old (and buggy) DOS word processor I had previously provided this with nary a complaint, I assumed it had to be hidden deep in WordPerfect’s settings, somewhere. It’s WordPerfect, for Christ’s sake! So I ran over the settings, looked into many of the lesser components, and went through all the documentation I could get my hands on, the manual of course, but third-party materials as well (considering there was no Web and most public libraries held few computer books at the time, not an effortless investigation). Then I called WordPerfect Support. Back then they deserved the capital S: Any of the good stories you’ve heard about their support I can only affirm. The first person I spoke to spent twenty minutes with me, going over what I had tried to get automatic first-line indenting. No to the settings. Nothing in the ini files (remember playing in ini files?). Nothing in templating would enable it. WordPerfect appeared quite dumb on the matter. Finally, after a few apologies, I was passed to another, slightly higher Support Specialist.

We started into the slightly magical realm of WordPerfect by going over what was (and wasn’t) possible using WordPerfect’s macro facility. As I’d already been there on my own, I explained what I’d tried for setting the Tab key to occur automatically. My thinking was, I have to hit the Enter key each time I want to start a new line, or paragraph. If I could get the Enter key to send a Tab before the new line, I’d be there! Nothing worked. Through the Support Specialist, I learned I could assign Tab to just about any key on my keyboard. Just not the Enter key, which was treated differently by WordPerfect.

Fat lot of help that would be to me.

Finally I hit my third level of support, referred to as a Senior Technician. We went over a summary of the last two levels (he had passed along the info about the limits of the Enter key with macros), but came to the conclusion that, as good as WordPerfect was, it wasn’t any good here. I was passed back to the starting support person, I assume to properly *close* the call. At that point I was informed that she had been informed that WordPerfect 6, due out late in the year, would provide automatic first-line indenting (I wonder if I’m responsible for that feature appearing in 6—if so, don’t bother thanking me). I appreciated the information (and the irony), but wasn’t willing to wait. And I’d just paid quite a bit of money for an application which couldn’t do what an older, cheap DOS-based one could. So I moved away from WordPerfect by exchanging my copy for Microsoft Word 2 (for Windows!), which despite any flaws could provide me with automatic first-line indenting. I knew this, because it said so right on the box!

So, what’s the moral? About year later I grabbed a copy of Microsoft Word 6, just released. Microsoft included complimentary copies of newsletters focused on their products. In the newsletter covering Word there was a Q&A section, in which one reader brought up a problem he was having whenever he turned on WordPerfect mode. Microsoft offers this setting in Word for former WordPerfect users, so they’re not required to relearn keyboard shortcuts and whatnot. And the problem this user was having? You must have already guessed: automatic first-line indenting stopped working. The answer from the “expert” was ambiguous at best, and provided no real explanation to what was going on, so I wrote a short note in response to let them both in on the secret: there was a Microsoft programmer out there who was far too good at his job.

If only I’d had a Microsoft Word wiki available to me at the time.