Notes on the Usable Help refresh
News at the speed of Twitter

More about the Usable Help refresh

I thought I'd answer a few questions about my previous post on this subject, and add a few details about the latest Tinderbox tinkering that I've done.

The source Tinderbox document for Usable Help is now almost five years old. That probably makes it the oldest, still "in-progress" document on my computer. However, as a result of its age, I found there were a lot of non-obvious, or just plain forgotten, dependencies in the export templates and Tinderbox attributes. After getting the initial redesign working, which as I said was sort of fun, I hit a brick wall of frustration.

It all started when I moved the Tinderbox document from the iMac's internal hard disk to an external FireWire drive that I carry with me when traveling. I moved the templates too, of course, but Tinderbox, unbeknownst to me, kept looking at the copies on the iMac's drive. As a result, exporting to HTML continued to work until I threw away the files on the iMac. Then several things broke in a mysterious and hard to debug fashion.

The short resolution is, after some speedy (and sympathetic) tech support from Mark Bernstein, I used BBedit to manually correct the template paths stored in the Tinderbox document. Theoretically, Tinderbox should have been able to sort this out itself after I set the document preferences, but my file had hundreds of embedded paths, most of which were wrong. I sure do wish that Tinderbox were less fragile about this, but I'm glad that the document format is so clean and easily hacked with a text editor. (One of the things I liked about it from the very beginning.) To be fair, the extent of my document's dependency on paths is likely due to its age, but if you're planning a similar project be sure to account for this possibility.

With hundreds of pages in the site, I was sure that no matter how closely I looked, I'd miss some problems. And I was right. A couple of readers alerted me that some graphics, embedded in the middle of articles, were missing. But only when the article was viewed via the "archives" page, and not when accessed directly. It turns out that during the redesign I accidentally dropped the obscure "base" tag in the head section of one template. Without this the paths to some graphics were pointing to the wrong place. Oops.

This weekend I re-instituted a feedback/response mechanism across the whole site. Adding the link involved getting the HTMLExportFileName, which didn't work as I expected, and the urlEncoded function to make sure everything got passed thru the PHP scripts in the correct formats. The problem I encountered with HTMLExportFileName is that if the attribute is empty, Tinderbox's automatically-generated substitute is only available during export time. That is, you can't use ^Get()^ to retrieve it. Since this impacted less than ten pages on my site, I used a server-side redirect to get around it. Mark suggested using a rule to set the value, but after wrestling with the aforementioned template problems, some of which were caused by overzealous agents, I'm gun shy about that approach.

There's still one aspect of the old site that I haven't touched, and that's the RSS feed. When it was first set up, Tinderbox's super-handy "urlEncoded" function didn't exist. Now that it does, I could certainly do more with the feed, but at this point I'm not convinced that a more modern format would offer true advantages. If you think that it would, visit Usable Help and use use my spiffy new "respond" feature to let me know. Thanks.


The comments to this entry are closed.