LispCast

In the last part of this series, I introduced the idea of Conceptual Models. I explained how the designer's model is communicated to the user only through the System Image. Well, I lied. While the System Image is the first thing the user sees, and it is very important in helping the user develop a good conceptual model, I simplified the case a bit. I displayed a diagram that showed a basic one-way communication between the system image and the user. This is actually not true. The beauty of using a library or any system is that the user is constantly revising his/her conceptual model based on information about the effect of each action. This process is called feedback.

Here's a diagram:

Feedback

The principle of feedback allows the user to immediately know the effect of his/her actions. A device or module that does not provide feedback is very hard to use. You have to guess whether you actually pressed the button hard enough, or if your command went through. Immediate feedback is important. We need feedback to understand what state the system is in in order to use it.

I'll discuss two important reasons for giving good feedback. First, feedback allows the user to evaluate and revise his/her conceptual model. This reason is important primarily to the programmer, since the programmer can learn from experience. Second, when there is good feedback, the current state of the system is evident. The user can easily determine the effect of his/her actions without guesswork or feats of memory. This aspect of feedback is important for both the programmer and his/her client code.

Revising the Conceptual Model

While at the REPL, the user continuously uses feedback to construct an accurate conceptual model. Each function call potentially changes the state of the system and queries the state of the system. The user tries to predict what the function does, then calls the function and analyzes the outcome, comparing it to his/her expectation. If the expectation is right, confidence goes up. If it's wrong, he/she'll need to revise the conceptual model.

Feedback is imperative to learning how a system works -- only the simplest of systems can be taught with documentation, comments, and examples alone. Proper feedback facilities should be considered as part of the system image, as should any other part that communicates to the user. In learning a system, you start with the static comments and documentation, and polish off your understanding with your own experimentation.

Gulf of Evaluation

Imagine, now, if the system did not provide feedback. How does the user know if his/her actions worked? How does he/she know if they performed as expected? The short answer is that the user doesn't know. The long answer is that he/she will have to guess, keeping track of it in his/her head. But if the user is wrong, well, the user is wrong, but doesn't know it. And that can be dangerous.

The difficulty a user has in determining the actual effect of his/her actions is called the Gulf of Evaluation.

Don't make your users climb down there. They could get hurt.

A good feedback system will have a small Gulf of Evaluation -- the effects of one's actions are clear and immediate. The size of the Gulf of Evaluation is proportional to the effort required to get and interpret feedback from the system. A corollary is that the ease of use and ease of learning a system is indirectly proportional to the size of the Gulf of Evaluation. Decreasing the Gulf of Execution is an important part of making the library feel intuitive.

Let us, for the moment, assume that the user is exactly right about how the system works. Why would the user want feedback, in that case? Well, if the system won't tell the user what state it's in, then the user is going to have to keep track of it in his/her head. And that will tire out the user's poor brain.

This is also exactly the reason why feedback is important to client code as well. Without programatic feedback for your client code to determine the state of the system, the client code will have to keep track of the state of the system itself. In fact, in order to function properly, the system will have to mimic the system exactly -- which is equivalent to rewriting the system. So then why would anyone want to use the library if they just have to rewrite it?

This idea of where knowledge of the system is kept -- in the world or in the head -- is crucial. It has everything to do with decoupling. It deserves a lot of attention, so I'll discuss it further in a later article.

What to do?

To return to the issue of feedback, what can we do to improve the design of our system?

Well, one thing we can do is to make functions return a value that indicates success or failure. In Lisp, NIL represents the empty list and the Boolean value false. This certainly doesn't make sense in all cases. The authors of the function GETHASH recognized this. GETHASH returns two values: the value associated with the key (or nil if it isn't found) and t or nil to indicate whether or not the key was associated. Why is this important? Why doesn't the first value suffice?

Well, let's imagine that GETHASH only returns the first value it now returns, namely the value associated with the given key. If we associate the value NIL with the key X, if we call (GETHASH 'X), we get the value NIL. And that is exactly the same answer we would have gotten with (GETHASH 'Y), even though Y is not associated with any value in the hash table.

So the key is to distinguish the two meanings with a second return value. The question the designer must ask him/herself is: "Are there any ambiguous values that I could disambiguate?" If the answer is yes, find a way to disambiguate them. Any impediments to learning the state of the system completely and unambiguously will slow down the learning of the system -- your library will seem confusing and difficult to use.

The designer should also add query functions to the system that allow the user to determine the state. This isn't to say that the internal implementation of the library should be exposed. But providing feedback functions gives you one more way to communicate an accurate conceptual model. The returned values of the query functions should correspond to the states and ideas that you as the designer want to communicate to the user.

One last thing you can do is to document your system in terms of the query functions. In your documentation, describe the output of these query functions after performing operations. For example:

;; If you call (ENQUEUE QUEUE 10) then (= 10 (LAST-IN-QUEUE QUEUE)) will return T

This will not only teach the user how to use the parts of the system (like the function ENQUEUE). It will also teach how to use the query functions to learn more about how the system works.

I hope you enjoyed this article. You've learned about Conceptual Models and Feedback, which let you teach the user how to use the system effectively. The next article will teach you to build your system to empower the user to avoid and fix his own errors.