Note Item Not Found

by Tony Austin
Principal, Asia/Pacific Computer Services

Q: Why did the Error Message cross the road?
A: To get the point across!

Or, putting another spin on it ...
Q: When is an Error Message not an Error Message?
A: When it doesn't convey readily useful information.

I was introduced to usability design in the mid-1970s, fairly early in my career at IBM Australia. This gave me a keen ongoing resolution to keep usability, efficiency, practicality and ease of use high on my list of priorities -- for all the products that I use personally and those that I deliver to my clients.

During recent years I've been on the lookout for of usability-related resources on the Web, and just in the last few weeks I came across some articles that got me pondering about error messages and error handling. Here are just a few resource sites relevant to the point I'm making software usability, error handling and error messages:

• Human Factors International and Good Experience and This Is Broken
• Software Testing Shouldn't Be Rocket Science - If you think that YOU are having a tough time debugging Notes/Domino software, read this to find out what they had to do to debug and fix radio problems with the Cassini spacecraft, launched way back in October 1997. ... "Good testing is about attitude, where a developer takes pride not just in the elegance or volume of his or her code, but in whether it meets the user's requirements and performs reliably in its first incarnation."
• Make your error messages meaningful - Many applications treat users as if they were programmers. Messages that report errors are often cryptic, contain meaningless codes, and provide no help regarding what to do next. While the developers who wrote the application can use those messages, most users are left with one option: call the help desk. This article describes a more appropriate kind of error message for users: one that includes description, cause, and recovery steps. (I worked extensively with IBM's System/36-System/38-AS/400, precursors to the current iSeries range, and their Help and error message support functions pretty much like this. In contrast, I've found this side of Notes -- and quite a few other PC-based products for that matter -- quite deficient and counter-productive.)
• Joel on Software (by Joel Spolsky) -- a rich feast, including Lord Palmerston on Programming with its concept of "programming worlds, each of which requires a tremendous amount of knowledge for real proficiency"
• Annoyances.org
• Dr Dobb's Journal and BYTE and SD Magazine

You'll find these links and many more like them on my web site, at http://asiapac.com.au/Links/Programming.htm (or its mirror http://notestracker.com/Links/Programming.htm) as well as http://asiapac.com.au/Links/Design.htm (or its mirror page http://notestracker.com/Links/Design.htm).

Seasoned IT practitioners will know that requirements analysis, design and programming is very hard work (at least it is if it's done conscientiously, thoroughly and professionally). No non-trivial piece of software is perfect -- not mine, not yours, not anybody else's. However even the best products have their blemishes and limitations.

The larger and more complex that a piece of software is, the more likely that it will contain minor or even major flaws. Incomplete analysis, wrong design assumptions, inferior coding implementations, unforeseen situations, the overstepping of functional limits, server and network performance limitations, general sloppiness and carelessness, all can lead to errors of one sort or another.

All the same, it's pleasantly surprising that things work as well as they do -- most of the time! Yet I never cease to be amazed how some rough edges and annoying behaviors seem never to be reported or publicly discussed, lingering on in what are otherwise outstanding products.

Is it just me who has noticed them? What about the product developers, testers, the marketers -- didn't they notice them? Or maybe they did, but the "powers that be" consider the deficiencies too insignificant (or costly, or awkward) to fix. I'm sure that many flaws survive because there's no easy and painless mechanism to report the deficiencies (bugs, usability issues, incorrect or obsolete or missing documentation, performance problems, and so on)?

It's far easier to be a destructive critic than to be a designer and builder! (And it certainly can be a humbling experience to have your own deliverables validly criticized.)

Don't get me wrong, I remain a dedicated Notes/Domino enthusiast, and it's in a vein of positive criticism I've submitted this article.

All the more so with the "buzz" coming out of last month's Lotusphere 2005 conference indicating that there's new IBM impetus behind Notes/Domino. The doomsayers stand confounded, So surely it's not too late in the product cycle for it to be worth fixing matters like the ones discussed below.

Some things that aren't all that Notes-worthy
Let me now change into "squeaky wheel" mode and illustrate my point via some of my pet peeves, niggling issues and bad experiences over the years with Lotus Notes/Domino and their companion products -- up to and including the very latest Beta3 (late January 2005) release of Notes Domino 7. Naturally I'd like to see any remaining Notes/Domino issues fixed before ND7 ships.

Below are a few things that I find particularly annoying and time-wasting.

Vague or Misleading Error Messages
What do you think is being indicated by the following Domino console log entry, which came up as soon as I started testing a new web agent (which came up as soon as I clicked on a URL for a Notes document in a Customer database)?

11/10/2003 07:06:49 PM HTTP Web Server: Lotus Notes Exception - Entry not found in index [/NotesTracker_Customer.NSF/27fb8884f5997b4dca256bba004168de/ba19bbf87ed08706ca256c6300242527?OpenDocument]

That's a real gem, isn't it? A model of clarity. It must be that a document is missing from a view index, since it says "Entry not found in index". What are those two IDs? Maybe the first is a view ID and the second is a document ID. Can I somehow trace which document is missing from the view? Where do I start? ... Help! Aidez moi! Aiuto!

In this case it turned out that it had nothing at all to do with any user documents in regular views. I had fallen into the common trap of incorrectly spelling the name of the web agent in the form's WebQueryOpen event. The index being referred was some sort of internal structure used by web agents, not some view index that I had any control over.

The error message should have told me something meaningful. such as: "Entry not found in index [NotesTrackerWebQueryOpen]" or better still "Agent not found [NotesTrackerWebQueryOpen]". Maybe the vague nature of the message derives from the original Domino Go Webserver code -- coming from a non-Domino source, IBM's Internet Connection Server (ICS), that was never tailored to fit Notes/Domino constructs such as web agents -- but to me that's "a reason, not an excuse".

Totally Obscure Error Messages
Now to explain the title for this article. It was way back in 1994 (Release 3 days, only my second year working with Notes). I was asked to enhance a database by secure some information a form with a signed field. I entered the necessary modifications to the form's design and confidently saved them. Then all hell broke loose - or that's how it felt to me at the time -- I had been in IT for some 25 years, but it was only my second year of my "programming world" with Notes).

Every time that I now attempted merely to open a document using the modified form design, I got nothing but a dialog box telling me "Note Item Not Found". Nothing else, just those four words. (This is but one example of Notes error messages that aren't documented anywhere at all. The same holds for quite a few other products. They all should be comprehensively documented. If you're lucky, you might find them described in some support knowledge base or other, but you're not always lucky.)

At the time, to me this was a totally meaningless and inscrutable message. In fact, it still is!
I asked myself questions like: What on earth does "Note Item not found" mean? What is meant by a "Note item"? (At that point in time I had never investigated the Notes C API, and not until a year or two later when LotusScript arrived on the scene with R4 did I learn what was meant by a Notes "Item" It certainly was never mentioned in any of the standard Notes classes conducted by Lotus Education.)

Why couldn't the message have told me which particular item was not found, and what was supposed to be happening during the opening of the document when the absence of the item caused the failure?

And what should I do to rectify the situation? Nothing, as it eventuated. There was nothing at all wrong with the form design. I learned a few weeks later later that the error was caused by a bug in Notes R3 with the handling of signed fields, and only a bug fix make the unwanted message go away.

I expected better, because of my IBM background working for years with the superb IBM System/38 and AS/400 systems, where the error messages are much more specific (and many of the messages advise you ins ome detail where to look and what to try in order to recover from the situation).

Inconsistent Behavior
"Little things are important," they say, and this is one of them. The inconsistent and off-putting behaviour that I'm discussing here first appeared, as far as I can recall, with Domino Designer R5 (but it might have been as far back as R4).

A developer often needs to have four or more windows open simultaneously (Notes client, Domino Designer, Web browser, Domino console, Help documentation, maybe a Java IDE, etc). Therefore screen real estate is at a premium, and she/he doesn't need any more windows open. Irritation aside, because of this inconsistency precious screen real estate is chewed up and your productivity is diminished.

The issue is this. When you're using Domino Designer against a database, opening some but not all of the various types of design element (forms, views, etc) automatically forces the Properties box to open, whether or not you want it open -- and often you want the Properties box to remain closed because it really gets in the way during some design activities (such as moving view columns around).

Unfortunately this errant behaviour persists in ND7 Beta 3, as follows:

• The Properties box quite properly remains closed when you edit a Frameset, Page, Form, Outline, Subform, Script Library, Navigator, Database Icon, Help About and Help Using documents, Database Script.
  
• It inappropriately opens when you edit a View or Folder, Agent, Web Service, Shared Field, Shared Column, Shared Action, Image (maybe), File Resource (maybe), Applet (maybe), Style Sheet (maybe), and Data Connection (maybe). Here, the "maybes" mean that it may be appropriate for the box to open when you click on the item, since there is not underlying form to open for each of these.

If you want the Properties box to remain closed, it definitely should not open against your wishes. There's no excuse for this unsystematic behaviour!

Time for a Break?
This one isn't to do with error messages and error handling as such, but it is "in the next ballpark" so to speak, and is certainly one of my pet peeves.

It's this: hitting the CTRL+BREAK keyboard shortcut is supposed to be "Stop operation in progress". Sometimes it does do that almost instantaneously.

However,sometimes it doesn't. I get extremely frustrated when the CTRL+BREAK key sequence has no immediate effect whatsoever, and Notes continues on its merry way for tens of seconds or even minutes. This tends to happen most often when you attempt to open a database that Notes has to hunt for and connot immediately locate. Notes then can "get the bit in its teeth" and start searching on goodness knows how many Domino servers across your network.

You may want to kill the search once you realize that clicking the Open button was a mistake, so you want CTRL+BREAK to immediately cancel the search for that database. But the keyboard locks up for what seems an eternity nd no amount of pounding on CTRL+BREAK has any effect. I sometimes have despaired and resorted to killing the entire Notes Client -- not at all an elegant solution, but at least I then get back to where I meant to be in ten or twenty seconds rather than minutes.

So another of my expectations is for the CTRL+BREAK key sequence to rapidly and consistently stop the current operation, whatever it is. (Just like CTRL+ALT+DEL nearly always does for Windows.) Get with it, Notes!


Have Your Say
I hope this article prompts you to think more keenly about usability, better error messages, and related matters. Am I being reasonable? Why do I sometimes feel a bit like the Tom hanks character, cast away on a remote island, and conversing with a volleyball to remain sane!

If you share similar concerns, here's a chance for you too to get them off your chest. Let me know how you feel about the above and any of your own problems and peeves with Notes Domino (and their related products).